はじめに
最初のアプリケーション
Flask はマイクロフレームワークです — 必須のものを提供し、必要なものは追加させてくれます。debug=True で自動リロードと詳細なエラーページが有効になります。
# install Flask
pip install flask
# app.py
from flask import Flask, render_template
app = Flask(__name__)
@app.route("/")
def home():
return render_template("index.html")
if __name__ == "__main__":
app.run(debug=True)開発サーバーの実行
組み込みサーバーを本番で使ってはいけません。FLASK_APP が app インスタンスを含むモジュールを指します。ネットワーク上から到達可能にするには --host=0.0.0.0 を使います。
# Set the entry point and enable debug mode
export FLASK_APP=app.py
export FLASK_ENV=development
flask run
# Override host and port
flask run --host=0.0.0.0 --port=5000
# Or run the module directly
python app.py仮想環境
仮想環境がプロジェクトの依存をシステムの Python から隔離します。requirements.txt が正確なバージョンを記録し、他の人が pip install -r requirements.txt で環境を再現できます。
# Create an isolated environment
python -m venv venv
# Activate (Linux/macOS)
source venv/bin/activate
# Activate (Windows PowerShell)
venv\Scripts\Activate.ps1
# Install dependencies
pip install flask
pip freeze > requirements.txtプロジェクト構成
Flask はレイアウトを強制しませんが、静的 ファイル、テンプレート、設定を分けるのが慣例です。instance/ フォルダは、バージョン管理されるべきでないデプロイ固有のシークレットを保持します。
myapp/
app.py # application factory or instance
config.py # configuration classes
requirements.txt # pinned dependencies
instance/
config.py # secret instance config (not in VCS)
static/ # CSS, JS, images
css/style.css
templates/ # Jinja2 templates
base.html
index.html
models.py # database models
views.py # route handlersアプリケーションファクトリパターン
ファクトリパターンはアプリの作成を関数が呼ばれるまで遅らせます。複数インスタンス、テスト、拡張には不可欠です。Flask の --app オプションは、アプリを返す呼び出し可能オブジェクトを受け付けます。
from flask import Flask
def create_app(config_name="default"):
app = Flask(__name__)
app.config.from_object(f"config.{config_name.title()}Config")
from .views import bp as views_bp
app.register_blueprint(views_bp)
@app.route("/health")
def health():
return {"status": "ok"}
return app
# Run with: flask --app myapp create_app run
# or export FLASK_APP=myapp:create_app最小アプリケーションの構造
__name__ を渡すと、Flask が静的ファイルとテンプレートを探す場所が伝わります。レイアウトがデフォルトと違うなら、コンストラクタ引数でフォルダの場所を上書きできます。
from flask import Flask
app = Flask(
__name__,
static_folder="static",
template_folder="templates",
static_url_path="/static",
)
# __name__ lets Flask locate resources relative to the module.
# Route decorators map URL patterns to view functions.
@app.route("/")
def index():
return "Hello, Flask!"ルーティング
可変ルール
<converter:varname> で印付けされたセクションが URL セグメントを取り込みます。組み込みのコンバーター:string(デフォルト)、int、float、path(スラッシュを受け付ける)、uuid。値は関数の引数として渡されます。
from flask import Flask
app = Flask(__name__)
@app.route("/user/<username>")
def show_user(username):
return f"User: {username}"
@app.route("/post/<int:post_id>")
def show_post(post_id):
return f"Post #{post_id}"
@app.route("/path/<path:subpath>")
def show_path(subpath):
return f"Path: {subpath}"URL コンバーター
コンバーターが URL 変数を検証し型変換します。正規表現パターンを強制するには、app.url_map.converters に BaseConverter のカスタムサブクラスを登録しましょう(製品コードなど)。
@app.route("/item/<int:item_id>")
def item_int(item_id):
return f"Integer ID: {item_id}"
@app.route("/weight/<float:kg>")
def weight(kg):
return f"{kg} kg"
@app.route("/uid/<uuid:token>")
def by_token(token):
return str(token)
# Custom converter
from werkzeug.routing import BaseConverter
class RegexConverter(BaseConverter):
def __init__(self, url_map, *items):
super().__init__(url_map)
self.regex = items[0]
app.url_map.converters["re"] = RegexConverter
@app.route("/code/<re:[a-z]{3}-[0-9]{4}:code>")
def code(code):
return code一意な URL とリダイレクト
末尾のスラッシュは重要です。'/' で終わるルートはスラッシュなしの形をリダイレクトし、'/' なしのルートはスラッシュ付きの形に 404 を返します。ルートごとに 1 つの慣例を選び、一貫させましょう。
@app.route("/projects/")
def projects():
return "Projects page"
# /projects/ -> 200 OK
# /projects -> 301 redirect to /projects/
@app.route("/about")
def about():
return "About page"
# /about -> 200 OK
# /about/ -> 404 Not FoundHTTP メソッド
複数の動詞を受け付けるには methods 引数を、単一メソッドのルートには @app.get / @app.post のショートカット(Flask 2.0+)を使います。GET がデフォルトです。
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
return do_login()
return render_template("login.html")
# Method-specific shortcuts
@app.get("/profile")
def profile_get():
return render_template("profile.html")
@app.post("/profile")
def profile_post():
return update_profile()url_for による URL 構築
url_for はエンドポイント名(デフォルトはビュー関数名)から URL を生成します。URL が変わっても耐え、_external=True を渡すと絶対 URL を作ります。
from flask import Flask, url_for
app = Flask(__name__)
@app.route("/")
def index():
# builds '/user/alice' instead of hardcoding
return f'<a href="{url_for("show_user", username="alice")}">Alice</a>'
@app.route("/user/<username>")
def show_user(username):
return f"Hello {username}"
with app.test_request_context():
print(url_for("show_user", username="bob")) # /user/bob1 ビューへの複数ルール
add_url_rule はデコレータなしで URL を登録します。各ルールに個別のエンドポイントを与えつつ、defaults 付きの同じビュー関数を指せば、1 つのハンドラが複数の URL 形に対応します。
from flask import Flask
app = Flask(__name__)
def show(id=None, name=None):
if id is not None:
return f"By id: {id}"
return f"By name: {name}"
app.add_url_rule("/by-id/<int:id>", "by_id", show, defaults={"name": None})
app.add_url_rule("/by-name/<name>", "by_name", show, defaults={"id": None})
# Two endpoints share one function with different defaults.リクエストとレスポンス
Request オブジェクト
request は現在のリクエストコンテキストに束縛されたスレッドローカルのプロキシです。明示的に渡されなくても、URL、メソッド、ヘッダー、ボディ、クライアント情報を公開します。
from flask import Flask, request
app = Flask(__name__)
@app.route("/info")
def info():
return {
"url": request.url,
"method": request.method,
"remote_addr": request.remote_addr,
"user_agent": str(request.user_agent),
"headers": dict(request.headers),
}レスポンスの作成
make_response でステータス、ヘッダー、ボディを完全に制御できます。単純なケースでは、文字列、辞書(JSON)、(body, status, headers) のタプルを返せます。
from flask import Flask, make_response
app = Flask(__name__)
@app.route("/")
def index():
resp = make_response("Hello, World!")
resp.status_code = 201
resp.headers["X-Custom"] = "yes"
resp.set_cookie("visited", "1")
return resp
# Returning a tuple: (body, status, headers)
@app.route("/quick")
def quick():
return "OK", 202, {"X-Quick": "1"}Response オブジェクト
カスタムの mimetype(XML、CSV など)やヘッダーが必要なら Response を使いましょう。Content-Disposition を attachment にすると、ブラウザがダウンロードを強制します。
from flask import Response
@app.route("/xml")
def xml():
return Response("<msg>hi</msg>", mimetype="application/xml")
@app.route("/text")
def text():
return Response("plain text", mimetype="text/plain")
@app.route("/csv")
def csv():
body = "a,b,c\n1,2,3\n"
headers = {"Content-Disposition": "attachment; filename=data.csv"}
return Response(body, mimetype="text/csv", headers=headers)カスタムのステータスとヘッダー
簡潔なカスタムレスポンスには (body, status, headers) のタプルを返しましょう。ボディなしの成功レスポンスには 204 No Content を、意味には標準の HTTP ステータスコードを使います。
@app.route("/created")
def created():
return "done", 201, {"Location": "/resource/1"}
@app.route("/no-content")
def no_content():
return "", 204
@app.route("/teapot")
def teapot():
return "I'm a teapot", 418ストリーミングレスポンス
ジェネレータの戻り値がデータをクライアントへストリーミングします。大きなファイル(全体をメモリにロードしない)や Server-Sent Events に有用です。適切な mimetype を設定しましょう。
from flask import Response
def generate():
yield "data: first\n\n"
yield "data: second\n\n"
yield "data: third\n\n"
@app.route("/stream")
def stream():
return Response(generate(), mimetype="text/event-stream")
@app.route("/big-file")
def big_file():
def chunks():
with open("large.log", "rb") as f:
while chunk := f.read(8192):
yield chunk
return Response(chunks(), mimetype="application/octet-stream")レスポンスへの Cookie
set_cookie が Set-Cookie ヘッダーを書き込み、delete_cookie が期限切れにします。セキュリティのため httponly と samesite を必ず設定しましょう。Cookie はレスポンスの一部であり、リクエストボディではありません。
from flask import make_response
@app.route("/set-theme")
def set_theme():
resp = make_response("theme set")
resp.set_cookie("theme", "dark", max_age=30*86400, httponly=True, samesite="Lax")
return resp
@app.route("/clear-theme")
def clear_theme():
resp = make_response("cleared")
resp.delete_cookie("theme")
return respRequest オブジェクト(form/args/files)
クエリパラメータ(args)
request.args はクエリ文字列の値の MultiDict です。デフォルトと型変換付きの get を使い、繰り返されるキーには getlist を使いましょう。直接インデックスアクセスは禁物です — キーが欠けると 400 が発生します。
from flask import request
@app.route("/search")
def search():
q = request.args.get("q", "") # default ""
page = request.args.get("page", 1, type=int)
tags = request.args.getlist("tag") # /search?tag=a&tag=b -> ["a","b"]
return {"q": q, "page": page, "tags": tags}フォームデータ
request.form が POST された application/x-www-form-urlencoded か multipart のデータを保持します。省略可能なフィールドでの KeyError を避けるため .get() を使いましょう。GET リクエストではフォームは空です。
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
username = request.form.get("username")
password = request.form.get("password")
if not username or not password:
return "Missing fields", 400
return f"Welcome {username}"
return render_template("login.html")ファイルアップロード
request.files は FileStorage オブジェクトの MultiDict です。保存前に、ユーザー提供のファイル名を必ず secure_filename に通し、パス区切りや危険な文字を取り除きましょう。
from flask import request
from werkzeug.utils import secure_filename
import os
@app.route("/upload", methods=["POST"])
def upload():
file = request.files.get("file")
if not file or file.filename == "":
return "No file", 400
name = secure_filename(file.filename)
file.save(os.path.join("uploads", name))
return "saved"JSON ボディ
get_json() は Content-Type が application/json のときだけボディを JSON としてパースします。force=True はヘッダーを無視し(慎重に使う)、silent=True はパースエラーを抑えます。
from flask import request
@app.route("/api/echo", methods=["POST"])
def echo():
data = request.get_json() # returns None if not JSON
if data is None:
return "Expected JSON", 415
return {"you_sent": data}
# Force parsing even without the right header (risky)
@app.route("/api/force")
def force():
data = request.get_json(force=True)
return dataヘッダーと Cookie
request.headers は EnvironHeaders の辞書風オブジェクトで、request.cookies はクライアントが送ってきた Cookie を保持します。どちらも読み取り専用です — ヘッダー/Cookie の設定はレスポンスに行いましょう。
from flask import request
@app.route("/inspect")
def inspect():
auth = request.headers.get("Authorization")
accept = request.headers.get("Accept")
session_id = request.cookies.get("session_id")
return {
"auth": auth,
"accept": accept,
"session_id": session_id,
}リクエストのメソッドとプロパティ
request は接続とボディのメタデータを公開します。is_json が Content-Type を、is_secure が HTTPS かどうかを確認し、query_string が '?' の後の生のバイト列です。
from flask import request
@app.route("/state")
def state():
return {
"method": request.method,
"is_xhr": request.is_json,
"content_type": request.content_type,
"content_length": request.content_length,
"is_secure": request.is_secure,
"scheme": request.scheme,
"host": request.host,
"path": request.path,
"query_string": request.query_string.decode(),
}Jinja2 テンプレート
テンプレートの描画
render_template が templates/ フォルダから Jinja2 ファイルをロードし、キーワード引数を変数として注入します。{{ }} 構文が式を出力し、Flask は安全性のため HTML を自動エスケープします。
from flask import render_template
@app.route("/<name>")
def hello(name):
return render_template("hello.html", name=name, title="Welcome")
# templates/hello.html
# <!DOCTYPE html>
# <html>
# <head><title>{{ title }}</title></head>
# <body>
# <h1>Hello {{ name }}!</h1>
# </body>
# </html>テンプレート変数
Jinja2 は属性(user.name)とアイテム(user['age'])のアクセスをサポートします。safe フィルタは文字列を信頼済みとして印付け、エスケープを免れさせます — 完全に制御できるコンテンツにだけ使いましょう。
# View
@app.route("/")
def index():
return render_template(
"index.html",
user={"name": "Alice", "age": 30},
items=["apple", "banana", "cherry"],
html_content="<b>safe?</b>",
)
# Template
# <p>Name: {{ user.name }}</p>
# <p>Age: {{ user["age"] }}</p>
# <p>First: {{ items[0] }}</p>
# <p>Raw HTML: {{ html_content | safe }}</p>制御構造
Jinja2 は {% if %}、{% for %}、{% block %} をサポートします。ループ内では特別な loop 変数が index、index0、first、last、length、revindex を与えます。for-else はイテラブルが空のとき実行されます。
{# if / elif / else #}
{% if user.age >= 18 %}
Adult
{% elif user.age >= 13 %}
Teen
{% else %}
Child
{% endif %}
{# for loop #}
<ul>
{% for item in items %}
<li>{{ loop.index }}: {{ item }}</li>
{% else %}
<li>No items</li>
{% endfor %}
</ul>テンプレートの継承
extends がベーステンプレートを取り込み、子テンプレートが名前付きブロックを上書きします。共有レイアウト(ナビゲーション、スクリプト)が 1 箇所に保たれます。super() が親ブロックの内容を描画します。
{# templates/base.html #}
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Default{% endblock %}</title>
</head>
<body>
{% block content %}{% endblock %}
</body>
</html>
{# templates/child.html #}
{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h1>Welcome home</h1>
{% endblock %}フィルタ
フィルタはパイプ(|)構文で値を変換し、引数を受け付けます。テンプレート間でロジックを再利用するには、app.jinja_env.filters にカスタムフィルタを登録しましょう。
{{ name | capitalize }} {# alice -> Alice #}
{{ price | round(2) }} {# 3.14159 -> 3.14 #}
{{ items | length }} {# count #}
{{ text | truncate(20) }} {# shorten #}
{{ tags | join(", ") }} {# ["a","b"] -> "a, b" #}
{{ value | default("n/a") }} {# fallback #}
{{ html | striptags }} {# remove HTML tags #}
{# Custom filter #}
def reverse_filter(s):
return s[::-1]
app.jinja_env.filters["reverse"] = reverse_filter
{{ "hello" | reverse }} {# olleh #}マクロ
マクロは関数のような、再利用可能なテンプレート断片です。{% from %} か {% import %} でインポートします。繰り返しの多い HTML(フォームフィールド、カード)を DRY に保てます。
{# templates/macros.html #}
{% macro input(name, value="", type="text") %}
<input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}
{% macro label(text, for_id) %}
<label for="{{ for_id }}">{{ text }}</label>
{% endmacro %}
{# In another template #}
{% from "macros.html" import input, label %}
<form>
{{ label("Username", "u") }}
{{ input("username") }}
{{ label("Password", "p") }}
{{ input("password", type="password") }}
</form>静的ファイル
静的ファイルの提供
Flask は静的フォルダのために /static/<path:filename> ルートを自動登録します。static_url_path が変わってもパスが正しいままになるよう、URL は必ず url_for で組み立てましょう。
# Files in the static/ folder are served at /static/<filename>
# static/css/style.css -> http://localhost:5000/static/css/style.css
# Reference them in templates
# <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
# <script src="{{ url_for('static', filename='js/app.js') }}"></script>
# <img src="{{ url_for('static', filename='img/logo.png') }}">静的アセットのための url_for
url_for('static', filename=...) が静的ファイルのパスを解決します。絶対 URL(メールやフィードで有用)には _external=True を、キャッシュバスティングにはクエリ引数を渡しましょう。
from flask import Flask, url_for
app = Flask(__name__)
with app.test_request_context():
print(url_for("static", filename="css/style.css"))
# /static/css/style.css
print(url_for("static", filename="js/app.js", _external=True))
# http://localhost/static/js/app.jsカスタム静的フォルダ
プロジェクトの慣例に合わせ、static_folder(ディスク上の場所)と static_url_path(URL 接頭辞)を上書きできます。デフォルトはフォルダ 'static' が /static にマッピングされたものです。
from flask import Flask
app = Flask(
__name__,
static_folder="assets", # folder on disk
static_url_path="/public", # URL prefix
)
# Now files in assets/ are served at /public/<filename>
# Template: url_for('static', filename='css/style.css') -> /public/css/style.cssFavicon
ブラウザはデフォルトでルートの /favicon.ico を要求します。明示的なルートを加えるか、<link> タグでアイコンをリンクしましょう。send_from_directory がディレクトリから安全にファイルを提供します。
from flask import send_from_directory
import os
@app.route("/favicon.ico")
def favicon():
return send_from_directory(
os.path.join(app.root_path, "static"),
"favicon.ico",
mimetype="image/vnd.microsoft.icon",
)
# Or place favicon.ico in static/ and link it:
# <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">キャッシュバスティング
ブラウザは静的アセットを URL でキャッシュします。バージョンハッシュを追記すれば、ファイルが変わった後にクライアントが新しいコピーを取得します。大きなプロジェクトでは、ビルドツール(Vite、Flask-Assets)がこれを自動化します。
# Append a version query param to force reloads
# <link href="{{ url_for('static', filename='css/app.css', v='1.2') }}">
# Or compute a hash at startup
import hashlib, os
def asset_version(filename):
path = os.path.join(app.static_folder, filename)
with open(path, "rb") as f:
return hashlib.md5(f.read()).hexdigest()[:8]
@app.template_filter("bust")
def bust(filename):
v = asset_version(filename)
return url_for("static", filename=filename) + f"?v={v}"
# Template: <link href="{{ 'css/app.css' | bust }}">Blueprint
Blueprint の作成
Blueprint は関連するルート、テンプレート、静的ファイルをモジュールへグループ化します。第 1 引数が blueprint の名前で、url_prefix が定義するすべてのルートにパスを先頭から付けます。
# auth.py
from flask import Blueprint, render_template
bp = Blueprint("auth", __name__, url_prefix="/auth")
@bp.route("/login")
def login():
return render_template("auth/login.html")
@bp.route("/register")
def register():
return render_template("auth/register.html")Blueprint の登録
register_blueprint が blueprint をアプリへ取り付けます。登録時に url_prefix を上書きできるため、同じ blueprint を異なるアプリで異なるパスの下にマウントできます。
from flask import Flask
from auth import bp as auth_bp
from blog import bp as blog_bp
app = Flask(__name__)
app.register_blueprint(auth_bp) # /auth/*
app.register_blueprint(blog_bp, url_prefix="/blog") # /blog/*
# Register later, or with a name override
app.register_blueprint(auth_bp, name="alt_auth")URL 接頭辞付きの Blueprint
url_prefix は Blueprint 上でも登録時にも定義できます。API パスのバージョン管理(/api/v1)により、既存クライアントを壊さずに後から /api/v2 を導入できます。
# api/__init__.py
from flask import Blueprint
bp = Blueprint("api", __name__, url_prefix="/api/v1")
@bp.route("/users")
def list_users():
return {"users": []}
@bp.route("/users/<int:uid>")
def get_user(uid):
return {"id": uid}
# All routes become /api/v1/users...Blueprint のリソース
blueprint は独自のテンプレートと静的フォルダを運べます。テンプレートの解決は blueprint を先に、次にアプリを調べるため、blueprint ローカルのファイルが同名のアプリ全体のものを上書きします。
bp = Blueprint(
"admin",
__name__,
url_prefix="/admin",
template_folder="templates", # blueprint-local templates
static_folder="static", # blueprint-local static
)
# Templates: blueprint lookups first, then app templates
# render_template("admin/dashboard.html")
# Static: url_for('admin.static', filename='css/admin.css')Blueprint のエラーハンドラ
blueprint レベルのエラーハンドラは、その blueprint のルートが発生させたエラーだけを捉えます。セクション固有のエラーページが作れます。アプリレベルのハンドラは捕まらなかったものを扱います。
from flask import Blueprint, render_template
bp = Blueprint("blog", __name__)
@bp.errorhandler(404)
def blog_not_found(e):
return render_template("blog/404.html"), 404
@bp.errorhandler(403)
def blog_forbidden(e):
return render_template("blog/403.html"), 403ネストした Blueprint
Flask 2.0+ は blueprint のネストをサポートします。親に register_blueprint で子を登録すれば、url_prefix が連結され、小さなモジュールから大きなアプリを組み立てられます。
from flask import Blueprint
parent = Blueprint("parent", __name__, url_prefix="/parent")
child = Blueprint("child", __name__, url_prefix="/child")
@child.route("/info")
def info():
return "nested info"
parent.register_blueprint(child)
app.register_blueprint(parent)
# Final URL: /parent/child/infoコンテキスト(g / session)
アプリケーションコンテキスト
アプリケーションコンテキストにより、リクエストの外(CLI コマンドやバックグラウンドタスクなど)でも current_app と g が使えます。リクエスト外で作業するときは app.app_context() で push しましょう。
from flask import current_app, g
@app.route("/")
def index():
app_name = current_app.name
config_value = current_app.config["SECRET_KEY"]
return f"Running {app_name}"
# Push a context manually (scripts, shell)
with app.app_context():
print(current_app.config["DEBUG"])g オブジェクト
g は、データベース接続のような共有リソースを保存するリクエストごとの名前空間です。リクエストごとにリセットされ、teardown_appcontext ハンドラで後始末されます。
from flask import g
import sqlite3
def get_db():
if "db" not in g:
g.db = sqlite3.connect("app.db")
g.db.row_factory = sqlite3.Row
return g.db
@app.teardown_appcontext
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()リクエストコンテキスト
リクエストコンテキストが request、session、url_for をスレッドに束縛します。テストやスクリプトでは、HTTP サーバーなしでリクエストをシミュレートするため test_request_context を使いましょう。
from flask import request
# Flask pushes a request context automatically during dispatch.
# Push one manually to use request/url_for outside a view:
with app.test_request_context("/?q=flask"):
print(request.args.get("q")) # flask
print(request.path) # /
# request_context for real WSGI environments
from werkzeug.test import EnvironBuilder
env = EnvironBuilder("/post/1").get_environ()
with app.request_context(env):
print(request.path)current_app と request のプロキシ
current_app、request、session、g は、アクティブなコンテキストへ属性アクセスを転送する LocalProxy です。グローバル変数に取り込んではいけません — 常に呼び出し時にアクセスしましょう。
from flask import current_app, request, session, g
# These are LocalProxy objects, not the real thing.
# They resolve to the current context's object at access time.
@app.route("/")
def index():
current_app.logger.info("hit /")
g.request_start = time.time()
session["visited"] = True
return current_app.config["APP_NAME"]
# Avoid storing proxies in module-level variables;
# always access them inside a context.Session オブジェクト
session は署名付きの Cookie ベースの辞書です。Flask が署名できるよう app.secret_key を設定しましょう。値はクライアント側に保存されユーザーが読めます(改ざんはできません)。シークレットは決して保存しないでください。
from flask import session
@app.route("/login")
def login():
session["user_id"] = 42
session["role"] = "admin"
return "logged in"
@app.route("/who")
def who():
uid = session.get("user_id")
return f"user {uid}" if uid else "anonymous"
@app.route("/logout")
def logout():
session.clear()
return "logged out"コンテキストのライフサイクル
ライフサイクルの理解が、フックを正しく使う鍵です。teardown_* ハンドラはエラー時でも必ず実行されるため、DB 接続を閉じリソースを解放する適切な場所です。
# Per-request lifecycle:
# 1. Application context pushed
# 2. Request context pushed
# 3. before_request handlers run
# 4. View function runs
# 5. after_request handlers run (can modify response)
# 6. Request context popped
# 7. teardown_request handlers run
# 8. teardown_appcontext handlers run (close resources)
@app.before_request
def before():
g.start = time.time()
@app.teardown_request
def teardown(exc):
elapsed = time.time() - getattr(g, "start", time.time())
app.logger.debug("request took %.3fs", elapsed)SQLAlchemy 統合
Flask-SQLAlchemy のセットアップ
Flask-SQLAlchemy が SQLAlchemy を包み、Flask のアプリコンテキストと統合します。SQLALCHEMY_DATABASE_URI に接続文字列を設定し、メモリ節約のため track modifications を無効化しましょう。
pip install flask-sqlalchemy
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
db = SQLAlchemy(app)
# In a factory, init with db.init_app(app)モデルの定義
モデルは db.Model を継承し、列は db.Column のインスタンスです。よくあるタイプには Integer、String、Text、DateTime、Boolean があります。制約には unique=True と nullable=False を使いましょう。
from datetime import datetime
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True, nullable=False)
email = db.Column(db.String(120), unique=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
def __repr__(self):
return f"<User {self.username}>"
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200), nullable=False)
body = db.Column(db.Text)
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))データのクエリ
Model.query が便利なクエリインターフェースです。filter_by(keyword=value) は単純で、filter(expression) は >、<、like、in_ などの演算子に対応します。paginate() がアイテムとページのメタデータを返します。
# Fetch all
users = User.query.all()
# Primary key lookup
user = User.query.get(1)
# Filter
admins = User.query.filter_by(role="admin").all()
active = User.query.filter(User.email.isnot(None)).first()
# Order, limit, paginate
recent = User.query.order_by(User.created_at.desc()).limit(10).all()
page = User.query.paginate(page=2, per_page=20)
# Count
total = User.query.count()追加と更新
すべての変更は db.session 経由のトランザクション内で起きます。add が新しいオブジェクトをステージングし、commit が書き込みます。エラー時には db.session.rollback() でロールバックし、セッションを使えるまま保ちましょう。
# Create
u = User(username="alice", email="[email protected]")
db.session.add(u)
db.session.commit()
# Update
u.email = "[email protected]"
db.session.commit()
# Delete
db.session.delete(u)
db.session.commit()
# Bulk insert
db.session.add_all([User(username="b"), User(username="c")])
db.session.commit()リレーション
db.relationship がモデル間のリンクを定義します。backref が逆向きの属性を加えます。lazy='dynamic' はリストの代わりにクエリオブジェクトを返し、さらにフィルタしたい大きなコレクションに有用です。
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80))
posts = db.relationship("Post", backref="author", lazy="dynamic")
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200))
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))
# Usage
user = User.query.get(1)
user.posts.all() # list of posts
post = Post.query.get(5)
post.author.username # backref to userFlask-Migrate による移行
Flask-Migrate が Alembic を包み、スキーマをバージョン管理します。migrate でモデル変更からスクリプトを自動生成し、upgrade で適用しましょう。コミット前に自動生成されたスクリプトを必ず見直してください。
pip install flask-migrate
from flask_migrate import Migrate
migrate = Migrate(app, db)
# CLI commands
# flask db init # create migrations folder
# flask db migrate -m "create users"
# flask db upgrade # apply migrations
# flask db downgrade # revert one step
# flask db current # show current revisionWTForms(Flask-WTF)
Flask-WTF のインストール
Flask-WTF が WTForms を Flask と統合し、CSRF 保護を自動的に加えます。CSRF トークンに署名するため SECRET_KEY が必要です。CSRF を無効化するのは公開 API エンドポイントだけにしましょう。
pip install flask-wtf
from flask import Flask
from flask_wtf import FlaskForm
app = Flask(__name__)
app.config["SECRET_KEY"] = "change-me-in-production"
app.config["WTF_CSRF_ENABLED"] = True
# CSRF protection is enabled by default
# when SECRET_KEY is set.フォームの定義
フォームは FlaskForm を継承します。各フィールドはラベルと、validate() で実行されるバリデーターのリストを取ります。バリデーターが必須入力、長さ、メール形式などを強制します。
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, SubmitField
from wtforms.validators import DataRequired, Email, Length
class LoginForm(FlaskForm):
email = StringField("Email", validators=[DataRequired(), Email()])
password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
submit = SubmitField("Log In")
class RegisterForm(FlaskForm):
username = StringField("Username", validators=[DataRequired(), Length(min=3, max=20)])
email = StringField("Email", validators=[DataRequired(), Email()])
submit = SubmitField("Sign Up")テンプレートへのフォーム描画
form.hidden_tag() が CSRF トークンと隠しフィールドを描画します。各フィールドはラベル、入力、エラーを個別に描画できます。手軽な出力には、{{ form.field() }} が HTML 入力を描画します。
{# templates/login.html #}
<form method="POST">
{{ form.hidden_tag() }} {# CSRF token #}
<p>
{{ form.email.label }}
{{ form.email() }}
{% for err in form.email.errors %}<span class="err">{{ err }}</span>{% endfor %}
</p>
<p>
{{ form.password.label }}
{{ form.password() }}
</p>
{{ form.submit() }}
</form>フォームのバリデーション
validate_on_submit() は、すべてのバリデーターが通った POST リクエストに対してだけ True を返します。成功時には form.field.data から値を読み、失敗時にはエラーを示すためテンプレートを再描画しましょう。
from flask import render_template, redirect, url_for, flash
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit(): # POST + valid
email = form.email.data
flash(f"Logged in as {email}")
return redirect(url_for("dashboard"))
return render_template("login.html", form=form)
# validate_on_submit() returns False on GET or invalid POST組み込みバリデーター
バリデーターは失敗時に ValidationError を発生させる呼び出し可能オブジェクトです。パスワード確認には EqualTo が一般的です。リストで連結すると、順に実行され 1 つでも失敗すれば止まります。
from wtforms.validators import (
DataRequired, # field not empty
Email, # valid email format
Length, # Length(min=3, max=20)
NumberRange, # NumberRange(min=0, max=100)
URL, # valid URL
Regexp, # Regexp(r"^\\w+$")
EqualTo, # EqualTo("password") - match another field
Optional, # skip validation if empty
InputRequired, # field submitted (even if empty string)
NoneOf, # NoneOf(["admin", "root"])
)
password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
confirm = PasswordField("Confirm", validators=[EqualTo("password")])FileField
アップロードの検証には、flask_wtf.file の FileField に FileRequired と FileAllowed を組み合わせましょう。アップロードされたファイルは form.field.data にある FileStorage オブジェクトです。form タグには enctype=multipart/form-data が必須です。
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed
class UploadForm(FlaskForm):
image = FileField("Image", validators=[
FileRequired(),
FileAllowed(["jpg", "png", "gif"], "Images only!"),
])
submit = SubmitField("Upload")
@app.route("/upload", methods=["GET", "POST"])
def upload():
form = UploadForm()
if form.validate_on_submit():
f = form.image.data
f.save("uploads/" + f.filename)
return "uploaded"
return render_template("upload.html", form=form)Flask-Login 認証
Flask-Login のセットアップ
Flask-Login がユーザーセッションを管理します:ログイン、ログアウト、ユーザーの記憶です。未認証ユーザーがリダイレクトされるよう login_view を設定しましょう。login_message がそのリダイレクトでフラッシュされます。
pip install flask-login
from flask import Flask
from flask_login import LoginManager
app = Flask(__name__)
app.config["SECRET_KEY"] = "secret"
login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = "login"
login_manager.login_message = "Please log in to access this page."User モデル
ユーザーモデルは UserMixin(is_authenticated、is_active、get_id などを提供)を mixin し、ID でユーザーを返す user_loader コールバックを実装する必要があります。平文のパスワードは保存せず、ハッシュ化しましょう。
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash
class User(UserMixin, db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True)
password_hash = db.Column(db.String(256))
def set_password(self, pw):
self.password_hash = generate_password_hash(pw)
def check_password(self, pw):
return check_password_hash(self.password_hash, pw)
@login_manager.user_loader
def load_user(user_id):
return User.query.get(int(user_id))ログインビュー
login_user がユーザーをセッションへ読み込みます。永続的な Cookie には remember=True を渡しましょう。ログイン前に必ずハッシュチェックでパスワードを検証し、失敗時には汎用的なエラーをフラッシュします。
from flask import render_template, redirect, url_for, flash
from flask_login import login_user
from forms import LoginForm
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit():
user = User.query.filter_by(username=form.username.data).first()
if user and user.check_password(form.password.data):
login_user(user, remember=form.remember.data)
return redirect(url_for("dashboard"))
flash("Invalid username or password")
return render_template("login.html", form=form)ルートの保護
@login_required デコレータは匿名ユーザーを拒否し login_view へリダイレクトします。current_user はログイン中のユーザー(または AnonymousUserMixin)へのプロキシで、ビューとテンプレートで使えます。
from flask_login import login_required, current_user
@app.route("/dashboard")
@login_required
def dashboard():
return f"Welcome {current_user.username}"
@app.route("/settings")
@login_required
def settings():
return render_template("settings.html", user=current_user)
# Unauthenticated users redirect to login_view
# @login_required must be the innermost decoratorログアウト
logout_user がユーザーをセッションから消去します。ログイン中のユーザーだけがログアウトできるよう、ルートは @login_required で保護しましょう。その後、公開ページ(index か login)へリダイレクトします。
from flask_login import logout_user, login_required
from flask import redirect, url_for, flash
@app.route("/logout")
@login_required
def logout():
logout_user()
flash("You have been logged out.")
return redirect(url_for("index"))
# logout_user() clears the session and cookiesRemember Me と current_user
remember=True が別の Cookie を設定し、ブラウザを閉じてもユーザーがログインし続けられます。current_user はビューでもテンプレートでも動くため、認証状態に基づいて UI を条件付きで描画しやすくなります。
from flask_login import current_user
# In the login view
login_user(user, remember=True)
# remember=True stores a separate long-lived cookie
# so the session survives a browser restart.
# current_user is available everywhere a context exists
@app.route("/")
def index():
if current_user.is_authenticated:
return f"Hi {current_user.username}"
return "Welcome, guest"
# In templates:
# {% if current_user.is_authenticated %}
# <a href="{{ url_for('logout') }}">Logout</a>
# {% endif %}エラー処理
abort()
abort() はビューを即座に停止し、HTTP エラーを返します。ステータスコードと省略可能なメッセージを渡します。Flask が一致するエラーレスポンスへ変換する HTTPException を発生させます。
from flask import abort
@app.route("/user/<int:id>")
def get_user(id):
user = find_user(id)
if user is None:
abort(404) # Not Found
if not can_access(user):
abort(403, "Forbidden") # Forbidden with description
return render_template("user.html", user=user)
# Common codes: 400 Bad Request, 401 Unauthorized,
# 403 Forbidden, 404 Not Found, 418 Teapot, 500 Server Errorカスタムエラーページ
@app.errorhandler(code) でハンドラを登録します。(template, status_code) のタプルを返しましょう。これらのハンドラは、abort() の呼び出しとそのステータスへ対応する例外の両方を捉えます。
from flask import render_template
@app.errorhandler(404)
def not_found(e):
return render_template("errors/404.html"), 404
@app.errorhandler(403)
def forbidden(e):
return render_template("errors/403.html"), 403
@app.errorhandler(500)
def server_error(e):
return render_template("errors/500.html"), 500例外のためのエラーハンドラ
ハンドラは HTTP コードだけでなくカスタム 例外クラスにも登録できます。ビューのどこで例外を発生させてもハンドラがトリガーされるため、ドメインエラーのレスポンスが一元化されます。
from werkzeug.exceptions import HTTPException
class InvalidUsage(Exception):
status_code = 400
def __init__(self, message, status_code=None, payload=None):
super().__init__()
self.message = message
if status_code is not None:
self.status_code = status_code
self.payload = payload
@app.errorhandler(InvalidUsage)
def handle_invalid_usage(e):
return {"error": e.message}, e.status_code
@app.route("/raise")
def raise_err():
raise InvalidUsage("Bad input", status_code=422)Catch-All の 404 ハンドラ
汎用の Exception ハンドラは 500 の最後の手段です。組み込みページが動き続けるよう HTTPException は再スローし、トレースバックを記録しましょう。本番でスタックトレースをユーザーへ漏らさないよう注意してください。
@app.errorhandler(404)
def page_not_found(e):
# Log the missing URL for analysis
app.logger.info("404: %s", request.path)
return render_template("errors/404.html", path=request.path), 404
@app.errorhandler(Exception)
def unhandled(e):
# Catch any uncaught exception -> 500
if isinstance(e, HTTPException):
return e
app.logger.exception("Unhandled error")
return render_template("errors/500.html"), 500エラーのロギング
完全なトレースバックを捉えるには、exc_info=True でログに記録しましょう。RotatingFileHandler がログファイルの際限ない成長を防ぎます。本番では、ログを一元化されたサービスへ送りましょう。
import logging
from logging.handlers import RotatingFileHandler
handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
handler.setLevel(logging.ERROR)
handler.setFormatter(logging.Formatter(
"%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
))
app.logger.addHandler(handler)
@app.errorhandler(500)
def server_error(e):
app.logger.error("Server error: %s", e, exc_info=True)
return "Internal error", 500HTTP 例外の処理
HTTPException はすべての Werkzeug HTTP エラーの基底クラスです。HTTPException に対するハンドラが一度にすべてを捉え、サブクラス固有のハンドラ(NotFound)がそのコードで優先されます。
from werkzeug.exceptions import HTTPException, NotFound, BadRequest
@app.errorhandler(HTTPException)
def handle_http_exception(e):
# All HTTP exceptions in one handler
return render_template(
"errors/generic.html",
code=e.code,
name=e.name,
description=e.description,
), e.code
# Specific subclasses still work
@app.errorhandler(NotFound)
def specific_404(e):
return "custom 404", 404JSON と API
jsonify
jsonify が Python の辞書/リストを、正しい Content-Type と ASCII セーフなエスケープ付きの JSON レスポンスへ変換します。Flask 2.1+ ではリストを直接渡せます。古いバージョンは辞書が必要です。
from flask import jsonify
@app.route("/api/user")
def api_user():
return jsonify(username="alice", age=30)
@app.route("/api/users")
def api_users():
users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
return jsonify(users)
# jsonify sets Content-Type: application/json
# and dumps with proper escapingJSON の返却
辞書やリストを直接返すのが、JSON を送る最も簡単な方法です。カスタムのステータスコードやヘッダーにはタプルを返しましょう。Response + json.dumps は、シリアライズを完全に制御したいときだけに。
# Returning a dict/list is auto-converted to JSON (Flask 1.1+)
@app.route("/api/quick")
def quick():
return {"status": "ok", "count": 42}
# With custom status and headers
@app.route("/api/created", methods=["POST"])
def created():
return {"id": 99}, 201, {"Location": "/api/99"}
# A Response with JSON body
from flask import Response
import json
@app.route("/api/raw")
def raw():
return Response(json.dumps({"k": "v"}), mimetype="application/json")JSON の受信
get_json() は Content-Type が application/json のときボディを JSON としてパースします。使う前に必ずパースされた構造を検証しましょう — クライアント入力を信頼してはいけません。不正なペイロードには 400/422 を返します。
from flask import request, jsonify
@app.route("/api/echo", methods=["POST"])
def echo():
data = request.get_json()
if not data:
return jsonify({"error": "Invalid JSON"}), 400
return jsonify({"received": data})
# Validate the structure
@app.route("/api/signup", methods=["POST"])
def signup():
data = request.get_json()
if not data or "email" not in data:
return jsonify({"error": "email required"}), 422
return jsonify({"email": data["email"]}), 201API Blueprint
API のルートは、バージョン管理された url_prefix(/api/v1)付きの blueprint でグループ化しましょう。API ロジックがページのルートから分離され、バージョン管理が明示的になります — 破壊的変更のときは /api/v2 へ上げます。
from flask import Blueprint, jsonify, request
api = Blueprint("api", __name__, url_prefix="/api/v1")
@api.route("/health")
def health():
return jsonify(status="ok")
@api.route("/items", methods=["GET", "POST"])
def items():
if request.method == "POST":
return jsonify(created=True), 201
return jsonify(items=[])
# Register: app.register_blueprint(api)CORS
flask-cors が Access-Control-Allow-Origin ヘッダーを加え、ブラウザがクロスオリジンのリクエストを許可します。本番ではワイルドカード '*' ではなく、信頼できるドメインへオリジンを制限しましょう。
pip install flask-cors
from flask import Flask
from flask_cors import CORS
app = Flask(__name__)
# Enable for all routes
CORS(app)
# Or restrict to specific origins
CORS(app, resources={r"/api/*": {"origins": ["https://example.com", "http://localhost:3000"]}})
# Per-route
@app.route("/api/public")
@cross_origin(origins="*")
def public():
return {"data": "open"}API エラーレスポンス
ヘルパー関数がエラーレスポンスをエンドポイント間で均一に保ちます — 同じ形状、同じキー名です。一貫したエラーボディはクライアント側のエラー処理をずっと容易にします。シークレットを漏らさない、デバッグに役立つ詳細を含めましょう。
from flask import jsonify, abort
def api_error(message, status=400, **extra):
body = {"error": message}
body.update(extra)
return jsonify(body), status
@app.route("/api/users/<int:id>")
def get_user(id):
user = find_user(id)
if not user:
return api_error("User not found", 404, user_id=id)
return jsonify(user.serialize())
# Consistent error shape across the API:
# {"error": "User not found", "user_id": 1}ファイルアップロード
基本のアップロード
ファイルアップロードのため、form タグには enctype=multipart/form-data が必要です。MAX_CONTENT_LENGTH を設定すれば、ボディを完全に読む前に過大なアップロードを 413 で拒否します — サーバーを守れます。
from flask import request
import os
app.config["UPLOAD_FOLDER"] = "uploads"
app.config["MAX_CONTENT_LENGTH"] = 16 * 1024 * 1024 # 16 MB
@app.route("/upload", methods=["POST"])
def upload():
file = request.files["file"]
file.save(os.path.join(app.config["UPLOAD_FOLDER"], file.filename))
return "uploaded"
# HTML form must include enctype:
# <form method="POST" enctype="multipart/form-data">
# <input type="file" name="file">
# <button>Upload</button>
# </form>安全なファイル名
secure_filename がユーザー提供のファイル名からディレクトリトラバーサルと危険な文字を取り除きます。一意性は保証しないため、上書きがリスクになるなら UUID を追記するか衝突を確認しましょう。
from werkzeug.utils import secure_filename
import os
@app.route("/upload", methods=["POST"])
def upload():
f = request.files.get("file")
if not f:
return "no file", 400
safe = secure_filename(f.filename) # "my file!!/x.txt" -> "my_file__x.txt"
if not safe:
return "invalid filename", 400
f.save(os.path.join("uploads", safe))
return f"saved as {safe}"複数のファイル
multiple 属性を持つ入力と共に request.files.getlist('files') を使えば、複数のファイルを一度に受け付けられます。保存前に各ファイルの拡張子とサイズを検証しましょう。
from flask import request
@app.route("/upload-many", methods=["POST"])
def upload_many():
files = request.files.getlist("files")
saved = []
for f in files:
if f and f.filename:
name = secure_filename(f.filename)
f.save(os.path.join("uploads", name))
saved.append(name)
return {"saved": saved}
# <form method="POST" enctype="multipart/form-data">
# <input type="file" name="files" multiple>
# </form>WTForms でのアップロード
Flask-WTF の FileField がアップロードの拡張子と存在を検証します。form タグには enctype=multipart/form-data が必須です。アップロードされたファイルは form.photo.data でアクセスできます。
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed
class PhotoForm(FlaskForm):
photo = FileField("Photo", validators=[
FileRequired(),
FileAllowed(["jpg", "jpeg", "png"], "Images only"),
])
submit = SubmitField("Upload")
@app.route("/photo", methods=["GET", "POST"])
def photo():
form = PhotoForm()
if form.validate_on_submit():
f = form.photo.data
f.save(os.path.join("uploads", secure_filename(f.filename)))
return "uploaded"
return render_template("photo.html", form=form)ファイルのタイプとサイズの検証
保存前に、拡張子とコンテンツ長の両方を検証しましょう。MAX_CONTENT_LENGTH が巨大なリクエストを早期に拒否しますが、ファイルごとのチェックがより細かい制御を与えます。より強い安全のため、拡張子だけでなくファイルのマジックバイトを検査しましょう。
import os
from flask import request
ALLOWED = {".png", ".jpg", ".jpeg", ".gif", ".pdf"}
MAX_SIZE = 5 * 1024 * 1024 # 5 MB
@app.route("/upload", methods=["POST"])
def upload():
f = request.files.get("file")
if not f or not f.filename:
return "no file", 400
ext = os.path.splitext(f.filename)[1].lower()
if ext not in ALLOWED:
return "file type not allowed", 415
f.stream.seek(0, 2) # seek to end
size = f.stream.tell()
f.stream.seek(0)
if size > MAX_SIZE:
return "file too large", 413
f.save(os.path.join("uploads", secure_filename(f.filename)))
return "ok"Before/After リクエストフック
before_request
before_request ハンドラは各ビューの前に動きます。認証チェック、メンテナンスモード、共有状態を g へのロードに使いましょう。値を返すとビューがスキップされ、そのレスポンスが直接使われます。
from flask import g, request
@app.before_request
def check_maintenance():
if app.config.get("MAINTENANCE"):
return "Site under maintenance", 503
@app.before_request
def load_user():
token = request.headers.get("Authorization")
if token:
g.user = verify_token(token)
# Return a value to short-circuit the requestafter_request
after_request ハンドラはビューの後に動き、レスポンスを受け取り返します。ヘッダーの追加、ロギング、キャッシュに最適です。未処理の例外が起きると、after_request はスキップされます。
@app.after_request
def add_security_headers(resp):
resp.headers["X-Content-Type-Options"] = "nosniff"
resp.headers["X-Frame-Options"] = "SAMEORIGIN"
return resp
@app.after_request
def log_response(resp):
app.logger.info("%s %s -> %s", request.method, request.path, resp.status_code)
return resp
# Must take and return a Response objectteardown_request
teardown_request は、after_request と違い、エラー時でもすべてのリクエストの終わりに動きます。例外(または None)を受け取り、DB 接続やファイルハンドルのようなリソースの解放に適した場所です。
import sqlite3
from flask import g
def get_db():
if "db" not in g:
g.db = sqlite3.connect("app.db")
return g.db
@app.teardown_request
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()
# teardown_request always runs, even if the view raisedbefore_first_request(非推奨)
before_first_request は、モダンな非同期サーバーやマルチプロセスの構成と相性が悪いため、Flask 2.3 で削除されました。1 回限りのセットアップは、インポート時のアプリコンテキスト内か、CLI コマンドで実行しましょう。
# Flask 2.3+ removed before_first_request.
# Old code:
# @app.before_first_request
# def init():
# warm_cache()
# Modern alternative: use the app context at startup
with app.app_context():
warm_cache()
# Or a CLI command run once during deployment
@app.cli.command("init")
def init_cmd():
warm_cache()レスポンスの修正
複数の after_request ハンドラは、逆登録順に連結されます。それぞれがレスポンスを返す必要があります。セキュリティヘッダー、キャッシュのディレクティブ、トレーシング ID に有用です。
@app.after_request
def no_cache(resp):
resp.headers["Cache-Control"] = "no-store"
resp.headers["Pragma"] = "no-cache"
return resp
@app.after_request
def add_request_id(resp):
rid = getattr(g, "request_id", "n/a")
resp.headers["X-Request-ID"] = rid
return resp
# Multiple after_request handlers run in reverse
# registration order; each receives the previous one's output.データベース接続のパターン
よくあるパターン:get_db(g に保存)で必要時に接続を開き、teardown_appcontext で閉じる。これで各リクエストが独自の接続を持ち、エラー時でも後始末が保証されます。
import sqlite3
from flask import g, current_app
def get_db():
if "db" not in g:
g.db = sqlite3.connect(
current_app.config["DATABASE"],
detect_types=sqlite3.PARSE_DECLTYPES,
)
g.db.row_factory = sqlite3.Row
return g.db
@app.teardown_appcontext
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()
@app.route("/users")
def users():
db = get_db()
rows = db.execute("SELECT * FROM users").fetchall()
return {"users": [dict(r) for r in rows]}CLI コマンド
カスタムコマンド
@app.cli.command で CLI コマンドを登録し、click の引数とオプションでデコレートします。docstring がヘルプテキストになります。利用可能なコマンドの一覧は flask --help で確認できます。
import click
from flask import Flask
app = Flask(__name__)
@app.cli.command("create-user")
@click.argument("name")
@click.option("--admin", is_flag=True, default=False)
def create_user(name, admin):
"""Create a new user."""
role = "admin" if admin else "user"
click.echo(f"Created {name} as {role}")
# Run: flask create-user alice --adminflask run
flask run が Werkzeug の開発サーバーを起動します。--debug でリローダーとインタラクティブなデバッガーが有効になり、--app でモジュールかファクトリを指定できます。このサーバーは本番では使いません — シングルスレッドで安全ではないためです。
# Basic
flask run
# Custom host/port
flask run --host=0.0.0.0 --port=8000
# Enable reloader and debugger
flask run --debug
# Specify the app explicitly
flask --app myapp run
flask --app myapp:create_app run
# With SSL (development)
flask run --cert=cert.pem --key=key.pemシェルコンテキスト
shell_context_processor が名前を flask shell へ注入し、インポートなしで実験できます。モデルのデバッグやアプリへのアドホッククエリに非常に有用です。
from flask import Flask
from models import db, User
app = Flask(__name__)
@app.shell_context_processor
def make_shell_context():
return {"db": db, "User": User, "app": app}
# flask shell
# >>> User.query.all()
# >>> db.session.add(User(username="x"))CLI 付きアプリケーションファクトリ
ファクトリパターンを使うときは、設定済みのアプリにアクセスできるよう CLI コマンドを create_app の内側に登録しましょう。Flask の --app オプションがファクトリを検出し、あなたの代わりに呼び出します。
# myapp/__init__.py
from flask import Flask
def create_app():
app = Flask(__name__)
app.config.from_object("config.Config")
@app.cli.command("init-db")
def init_db():
"""Initialize the database."""
click.echo("Initialized")
return app
# Run: flask --app myapp init-db
# The factory is detected automatically.CLI グループ
関連するコマンドは @app.cli.group の親の下にグループ化しましょう。サブコマンドはグループに登録され、CLI が整理されます:flask db init、flask db migrate など。
import click
from flask import Flask
app = Flask(__name__)
@app.cli.group("db")
def db_group():
"""Database commands."""
pass
@db_group.command("init")
def db_init():
click.echo("DB initialized")
@db_group.command("drop")
def db_drop():
click.echo("DB dropped")
# flask db init
# flask db drop環境変数
CLI は FLASK_APP と FLASK_DEBUG で設定します。共有の開発設定には .flaskenv、シークレットには .env を使いましょう(python-dotenv があれば両方自動読み込み)。.flaskenv は通常コミットされるため、シークレットは入れないでください。
# Flask reads these env vars:
# FLASK_APP -> module/app to run (app.py, myapp, myapp:create_app)
# FLASK_DEBUG -> 1/0 to toggle debug mode
# FLASK_ENV -> development/production (deprecated, use FLASK_DEBUG)
# FLASK_RUN_PORT -> default port
# FLASK_RUN_HOST -> default host
# .env or .flaskenv files are auto-loaded by python-dotenv
# .flaskenv (committed): FLASK_APP=app.py
# .env (gitignored): SECRET_KEY=..., DATABASE_URL=...
# Prefer app.config.from_envvar or from_object for app secrets.テスト
Test Client の基本
test_client() がネットワークなしでリクエストを送るクライアントを返します。より良いエラーメッセージとエラー捕捉の無効化のため TESTING=True を設定しましょう。各テストが新しいアプリを得られるよう fixture を使いましょう。
import pytest
from myapp import create_app
@pytest.fixture()
def client():
app = create_app()
app.config["TESTING"] = True
with app.test_client() as client:
with app.app_context():
pass # init DB here
yield client
def test_home(client):
resp = client.get("/")
assert resp.status_code == 200
assert b"Hello" in resp.dataテストでのリクエスト
テストクライアントはブラウザを模倣します:data(フォーム)、json、query_string、headers 付きの get/post/put/delete。JSON レスポンスのパースには resp.get_json() を、ヘッダーの検査には resp.headers を使いましょう。
def test_get(client):
resp = client.get("/users/1")
assert resp.status_code == 200
def test_post_form(client):
resp = client.post("/login", data={"username": "a", "password": "b"})
assert resp.status_code == 302 # redirect
def test_post_json(client):
resp = client.post("/api/echo", json={"key": "value"})
assert resp.get_json() == {"received": {"key": "value"}}
def test_query(client):
resp = client.get("/search?q=flask&page=2")
assert resp.status_code == 200
def test_headers(client):
resp = client.get("/", headers={"X-Test": "1"})JSON API のテスト
json=... を渡せば、正しい Content-Type 付きで JSON ボディが送られます。ステータス、パースされた JSON ボディ、Location のようなヘッダーを assert しましょう。成功とエラーの両経路のテストで、API が一貫して振る舞うことが保証されます。
def test_create_user(client):
resp = client.post(
"/api/users",
json={"username": "alice", "email": "[email protected]"},
)
assert resp.status_code == 201
body = resp.get_json()
assert body["username"] == "alice"
assert "id" in body
assert resp.headers["Location"].endswith(str(body["id"]))
def test_error(client):
resp = client.post("/api/users", json={})
assert resp.status_code == 422
assert "error" in resp.get_json()pytest の Fixture
Fixture が再利用可能なセットアップを提供します:メモリ内データベース、テストクライアント、CLI ランナー。リソースを yield し、後に後始末しましょう。test_cli_runner() がテスト内で CLI コマンドを呼び出し、出力と終了コードを確認します。
import pytest
from myapp import create_app, db
@pytest.fixture()
def app():
app = create_app()
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
with app.app_context():
db.create_all()
yield app
db.drop_all()
@pytest.fixture()
def client(app):
return app.test_client()
@pytest.fixture()
def runner(app):
return app.test_cli_runner()
def test_cli(runner):
result = runner.invoke(args=["create-user", "alice"])
assert result.exit_code == 0テスト用データベース
速く隔離されたテストにはメモリ内の SQLite データベースを使いましょう。fixture の内側でテーブルを作成しデータを投入し、後にすべて削除します。各テストがまっさらな状態で始まるため、テスト間の汚染が防げ ます。
import pytest
from myapp import create_app, db
from myapp.models import User
@pytest.fixture()
def app():
app = create_app()
app.config["TESTING"] = True
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
with app.app_context():
db.create_all()
db.session.add(User(username="alice"))
db.session.commit()
yield app
db.session.remove()
db.drop_all()
def test_user_count(app):
with app.app_context():
assert User.query.count() == 1モック
patch が外部の呼び出し(HTTP、メール、キュー)をモックに置き換え、テストが速く決定的に保たれます。期待する引数でモックが呼ばれたことを assert しましょう。patch は、定義場所ではなく名前が検索される場所へ行いましょう。
from unittest.mock import patch, MagicMock
import myapp
def test_external_call(client):
with patch("myapp.requests.get") as mock_get:
mock_get.return_value = MagicMock(status_code=200, json=lambda: {"ok": True})
resp = client.get("/proxy")
assert resp.status_code == 200
mock_get.assert_called_once()
def test_email(client):
with patch("myapp.send_email") as mock_send:
client.post("/register", data={"email": "[email protected]"})
mock_send.assert_called_once_with("[email protected]", "Welcome!")デプロイ
本番サーバーの警告
Werkzeug の開発サーバーはシングルスレッドで安全ではありません — インターネットに晒してはいけません。リバースプロキシの後ろで本番の WSGI サーバー(Gunicorn、uWSGI、Waitress)を使いましょう。debug のデバッガーはリモートコード実行のリスクです。
# WARNING: Flask's built-in server is for development only!
# app.run() / flask run -> single-threaded, no security, not scalable
# For production use a WSGI server:
# - Gunicorn (Linux/macOS)
# - uWSGI
# - Waitress (Windows-friendly)
# Behind a reverse proxy (Nginx, Apache, Caddy)
# The dev server also enables the interactive debugger
# when debug=True, which allows arbitrary code execution.
# NEVER deploy with debug=True.Gunicorn
Gunicorn は Linux/macOS で最も人気のあ る WSGI サーバーです。workers の公式 (2 × CPU + 1) が良い出発点です。Nginx の後ろでは 127.0.0.1 に束縛し、TLS と静的ファイルはプロキシに任せましょう。
pip install gunicorn
# Basic
gunicorn "app:app"
# With factory
gunicorn "myapp:create_app()"
# Workers and binding
gunicorn -w 4 -b 0.0.0.0:8000 "app:app"
# With timeout and logging
gunicorn -w 4 -b 0.0.0.0:8000 --timeout 120 --access-logfile - "app:app"
# Recommended workers: (2 * CPU) + 1
# Use --preload to share memory, or -k gevent for async.uWSGI
uWSGI は高性能で高度に設定可能な WSGI サーバーです。master プロセスがワーカーを管理し、vacuum が終了時に後始末します。最良のスループットのため、uwsgi プロトコルで Nginx と組み合わせましょう。
pip install uwsgi
# Command line
uwsgi --http 0.0.0.0:8000 --module app:app --processes 4 --threads 2
# INI config (uwsgi.ini)
# [uwsgi]
# module = app:app
# http = 0.0.0.0:8000
# processes = 4
# threads = 2
# master = true
# vacuum = true
# die-on-term = true
# Run: uwsgi uwsgi.iniリバースプロキシ(Nginx)
Nginx が Gunicorn の前に座ります:静的ファイルを直接提供し(より速い)、TLS を終端し、リクエストを WSGI サーバーへ転送します。X-Forwarded-* ヘッダーで、Flask が実際のクライアント IP とスキーマを見られます — 信頼するため ProxyFix を設定しましょう。
# /etc/nginx/sites-available/myapp
server {
listen 80;
server_name example.com;
location /static/ {
alias /path/to/app/static/;
expires 30d;
}
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
}
}Docker
スリムな Python ベースイメージがイメージを小さく保ちます。Docker のレイヤーキャッシュを活用するため、コードのコピー前に依存をインストールしましょう。シークレットは環境変数(--env-file)で渡し、イメージに焼き込まないでください。
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]
# .dockerignore
# __pycache__/
# venv/
# *.pyc
# .env
# Build and run
# docker build -t myapp .
# docker run -p 8000:8000 --env-file .env myapp環境設定
設定をレイヤー化しましょう:コード内のデフォルト、環境固有の上書き、env 変数からの instance シークレット。これでシークレットがソース管理から離れ、1 つのコードベースが dev、staging、本番で動きます。
import os
from flask import Flask
app = Flask(__name__)
app.config.from_object("config.DefaultConfig")
# Override with environment-specific config
env = os.environ.get("FLASK_ENV", "development")
app.config.from_object(f"config.{env.title()}Config")
# Then instance-specific secrets from env vars
app.config["SECRET_KEY"] = os.environ["SECRET_KEY"]
app.config["SQLALCHEMY_DATABASE_URI"] = os.environ["DATABASE_URL"]
# Use python-dotenv for local .env files
from dotenv import load_dotenv
load_dotenv()設定
Config オブジェクト
設定は、基底の Config を継承するクラスとして定義しましょう。環境ごとに変わるものだけを上書きします。from_object が大文字の属性を app.config へコピーするため、小文字のヘルパーは無視されます。
class Config:
DEBUG = False
TESTING = False
SECRET_KEY = "change-me"
SQLALCHEMY_DATABASE_URI = "sqlite:///app.db"
class DevelopmentConfig(Config):
DEBUG = True
SECRET_KEY = "dev-secret"
class ProductionConfig(Config):
DEBUG = False
SECRET_KEY = os.environ["SECRET_KEY"]
class TestingConfig(Config):
TESTING = True
SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
app.config.from_object(DevelopmentConfig)環境変数
シークレットには os.environ を使い、コードに存在させないようにしましょう。from_envvar が env 変数が指す Python ファイルを読み込みます — デプロイ固有の上書きに有用です。ローカル開発では python-dotenv が .env ファイルを読み込みます。
import os
from flask import Flask
app = Flask(__name__)
# Read individual values
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev")
app.config["DATABASE_URL"] = os.environ.get("DATABASE_URL", "sqlite:///app.db")
# Load a whole config file from an env var path
# export MYAPP_SETTINGS=/etc/myapp/prod.py
app.config.from_envvar("MYAPP_SETTINGS", silent=True)
# python-dotenv loads .env automatically if installed
from dotenv import load_dotenv
load_dotenv()Instance フォルダ
instance フォルダが、バージョン管理の外にデプロイ固有のファイル(シークレット、設定)を保持します。instance_relative_config=True を設定し、from_pyfile で読み込みましょう。これでコードと環境設定がきれいに分離されます。
# The instance/ folder sits outside the package, not in VCS.
# Flask searches it automatically for config files.
app = Flask(__name__, instance_relative_config=True)
# Load from instance/config.py
app.config.from_pyfile("config.py", silent=True)
# instance/config.py (deployment-specific, gitignored)
# SECRET_KEY = "real-production-key"
# SQLALCHEMY_DATABASE_URI = "postgresql://user:pass@db/app"
# Access the path
print(app.instance_path) # /abs/path/to/instanceファイルからの設定
from_object がモジュールかオブジェクトのパスをインポートし、from_pyfile が絶対パスのファイルを読み込み、from_file(Flask 2.0+)がローダー関数を使い JSON、TOML、YAML に対応します。1 つの形式を選び、一貫させましょう。
# config.py
DEBUG = True
SECRET_KEY = "dev"
SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"
# Load a Python file
app.config.from_object("config")
# Load by path
app.config.from_pyfile("/etc/myapp/config.py")
# Load from a JSON file
app.config.from_file("config.json", load=json.load)
# config.json
# { "DEBUG": true, "SECRET_KEY": "dev" }開発と本番の違い
環境変数で設定を切り替えれば、同じコードがどこでも動きます。本番では debug を必ず無効化し(デバッガーはセキュリティホール)、本物のデータベースを使いましょう。本番で debug が有効なら警告をログに残しましょう。
import os
from flask import Flask
env = os.environ.get("FLASK_ENV", "development")
configs = {
"development": DevelopmentConfig,
"production": ProductionConfig,
"testing": TestingConfig,
}
app = Flask(__name__)
app.config.from_object(configs[env])
# In production, never enable debug:
if app.config["DEBUG"]:
print("WARNING: running in debug mode!")ロギングの設定
ロギングの設定は debug モードでないときだけにしましょう(debug 中、Flask はデフォルトで stderr に記録します)。RotatingFileHandler が際限のないログの成長を防ぎます。本番では、集約サービスのために構造化された JSON ロギングを検討しましょう。
import logging
from logging.handlers import RotatingFileHandler
if not app.debug:
handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
handler.setFormatter(logging.Formatter(
"%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
))
handler.setLevel(logging.INFO)
app.logger.addHandler(handler)
app.logger.setLevel(logging.INFO)
# In a view
@app.route("/")
def index():
app.logger.info("Index page accessed")
return "Hello"
# Flask's logger is a standard logging.Logger関連する Flask スニペット
Copy-paste ready code for common tasks.
Routing
Define routes with methods and dynamic parameters.
Request and Response
Access request data and build custom responses.
Jinja2 Templates
Render templates with context and template inheritance.
Blueprints
Organize an app into modular blueprints.
Session
Store per-user data in signed session cookies.
Error Handling
Register custom error handlers for HTTP exceptions.
Flask-SQLAlchemy
Define models and query them with Flask-SQLAlchemy.
Custom Decorators
Build decorators to gate or augment view functions.
Was this helpful?