Flask アプリケーションオブジェクト API
Flask クラスはフレームワーク全体の中核であり、WSGI アプリケーションとして動作し、ルーティング、テンプレート、設定、フックなどのすべての機能を一元管理します。
作成方法:
app = Flask(__name__)
コンストラクタ引数
以下は、Flask インスタンスを作成するときに渡すことができるすべての引数です:
| 引数 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| import_name | str | 必須 | アプリケーションモジュール/パッケージ名。Flask はこれを使用してテンプレートと静的ファイルの場所を特定します。単一ファイルの場合は __name__ を渡し__name__、パッケージの場合はパッケージ名を渡します |
| static_url_path | str | None | 静的ファイルを外部に公開する URL パス。未設定の場合は static_folder のフォルダ名を使用します(例: /static) |
| static_folder | str | "static" | 静的ファイル(CSS、JS、画像)を格納するフォルダパス。root_path からの相対パスまたは絶対パス |
| static_host | str | None | 静的ファイルルーティングのホスト名。host_matching=True の場合のみ必要 |
| host_matching | bool | False | Host ヘッダーに基づいてルーティングをマッチングするかどうか |
| subdomain_matching | bool | False | サブドメインルーティングのマッチングを有効にするかどうか |
| template_folder | str | "templates" | Jinja2 テンプレートファイルを格納するフォルダパス |
| instance_path | str | None(自動検出) | instance フォルダのパス。実行時にバージョン管理にコミットしないファイルを格納します。絶対パスに設定します |
| instance_relative_config | bool | False | True の場合、設定ファイルの相対パスは root_path ではなく instance_path に基づきます |
| root_path | str | None(自動検出) | アプリケーションのルートパス。通常は自動的に推測されます。名前空間パッケージの場合のみ手動設定が必要です |
コア属性
| 属性 | 型 | 説明 |
|---|---|---|
| name | str | アプリケーション名。import_name が __main__ の場合、メインファイル名が使用されます |
| config | Config | 設定辞書オブジェクト。すべての設定項目を格納します |
| debug | bool | デバッグモードを有効にするかどうか。config["DEBUG"] と同等 |
| testing | bool | テストモードを有効にするかどうか。config["TESTING"] と同等 |
| secret_key | str | セキュリティキー。Session の署名に使用されます。config["SECRET_KEY"] と同等 |
| permanent_session_lifetime | timedelta | 永続 Session の有効期限。デフォルトは 31 日 |
| url_map | Map | Werkzeug の URL マップテーブル。すべてのルーティングルールを格納します |
| view_functions | dict | endpoint → ビュー関数のマッピング辞書 |
| blueprints | dict | 登録済みブループリント名 → Blueprint インスタンスのマッピング |
| extensions | dict | 拡張機能のストレージ辞書。拡張機能はモジュール名ごとに自身の状態を格納します |
| logger | Logger | Python 標準の logging.Logger。アプリケーション名がロガー名として使用されます |
| jinja_env | Environment | Jinja2 環境インスタンス。テンプレートの読み込み方法を制御します |
| json | JSONProvider | JSON 処理プロバイダーインスタンス。カスタム JSON ライブラリに置き換え可能 |
| aborter | Aborter | HTTP 例外スローワー。abort() 関数から呼び出されます |
| cli | AppGroup | Click コマンドグループ。カスタム CLI コマンドを追加できます |
| instance_path | str | instance フォルダの絶対パス |
| root_path | str | アプリケーションルートディレクトリの絶対パス |
オーバーライド可能なクラス属性
以下の属性はサブクラスでオーバーライドして、フレームワークの動作をカスタマイズできます:
| 属性 | デフォルト値 | 説明 |
|---|---|---|
| request_class | Request | リクエストオブジェクトを作成するためのクラス |
| response_class | Response | レスポンスオブジェクトを作成するためのクラス |
| session_interface | SecureCookieSessionInterface() | Session バックエンドインターフェース。Redis/データベース Session に置き換え可能 |
| jinja_environment | Environment | Jinja2 環境クラス |
| app_ctx_globals_class | _AppCtxGlobals | g オブジェクトのクラス |
| config_class | Config | 設定オブジェクトのクラス |
| aborter_class | Aborter | 例外スローワーのクラス |
| json_provider_class | DefaultJSONProvider | JSON プロセッサのクラス |
| url_rule_class | Rule | URL ルールのクラス(Werkzeug) |
| url_map_class | Map | URL マップテーブルのクラス(Werkzeug) |
| test_client_class | None(デフォルトは FlaskClient) | テストクライアントのクラス |
| test_cli_runner_class | None(デフォルトは FlaskCliRunner) | CLI テストランナーのクラス |
| jinja_options | {} | Jinja2 環境に渡される追加オプション |
URL ルーティングメソッド
| メソッド | シグネチャ | 説明 |
|---|---|---|
| route | (rule, **options) | デコレータ。URL ルールをビュー関数にバインドします |
| get | (rule, **options) | デコレータ。GET メソッドのみをバインドします(methods=["GET"] と同等) |
| post | (rule, **options) | デコレータ。POST メソッドのみをバインドします |
| put | (rule, **options) | デコレータ。PUT メソッドのみをバインドします |
| delete | (rule, **options) | デコレータ。DELETE メソッドのみをバインドします |
| patch | (rule, **options) | デコレータ。PATCH メソッドのみをバインドします |
| add_url_rule | (rule, endpoint, view_func, provide_automatic_options, **options) | プログラムで URL ルールを追加します。route デコレータは内部でこのメソッドを呼び出します |
| url_for | (endpoint, *, _anchor, _method, _scheme, _external, **values) | endpoint と引数に基づいて URL を生成します。ブループリント内では endpoint にブループリント名のプレフィックスを付ける必要があります |
| register_blueprint | (blueprint, **options) | ブループリントを登録します。url_prefix、subdomain などの上書きパラメータを指定できます |
| iter_blueprints | () | 登録順にすべてのブループリントを反復処理します |
route デコレータがサポートする options は次のとおりです:methods(HTTP メソッドリスト)、endpoint(カスタムエンドポイント名)、defaults(デフォルト引数)、subdomain(サブドメイン)などです。
リクエストライフサイクルフック(デコレータ)
以下のメソッドはすべてデコレータとして使用でき、リクエストのさまざまな段階でカスタムロジックを挿入できます。
| メソッド | 実行タイミング | 非 None を返した場合の動作 | 典型的な用途 |
|---|---|---|---|
| before_request | ルーティングディスパッチ前 | 戻り値が最終レスポンスとして使用され、ビュー関数をスキップします | ログイン確認、権限検証 |
| after_request | レスポンス構築後、送信前 | Response オブジェクトを受け取り、返す必要があります | セキュリティヘッダー、CORS ヘッダーの追加 |
| teardown_request | リクエストコンテキストがポップされるとき | 戻り値は無視されます | リクエストレベルのリソースを解放します |
| teardown_appcontext | アプリケーションコンテキストがポップされるとき | 戻り値は無視されます | データベース接続を閉じます |
| errorhandler | 指定されたステータスコードまたは例外が発生したとき | 戻り値がエラーページのレスポンスとして使用されます | カスタム 404/500 ページ |
| url_value_preprocessor | URL 変数が抽出された後、ビューが呼び出される前 | 戻り値は無視されます | URL パラメータの前処理を行います |
| url_defaults | url_for が URL を構築するとき | 渡された values 辞書を変更します | url_for にデフォルト引数を追加します |
| template_filter | —(登録性質) | — | Jinja2 テンプレートフィルターを登録します |
| template_test | —(登録性質) | — | Jinja2 テンプレートテストを登録します |
| template_global | —(登録性質) | — | Jinja2 グローバル関数を登録します |
| shell_context_processor | flask shell 起動時 | dict を返し、シェルコンテキストにマージします | よく使うオブジェクトを flask shell に事前インポートします |
リクエスト処理メソッド
以下のメソッドはリクエスト処理フローの中で内部的に呼び出され、サブクラスでオーバーライドできます:
| メソッド | 説明 |
|---|---|
| preprocess_request(ctx) | リクエスト前処理:before_request 関数と URL プリプロセッサを実行します |
| dispatch_request(ctx) | コアディスパッチ:URL をマッチングし、対応するビュー関数を呼び出します |
| make_response(rv) | ビュー関数の戻り値を Response オブジェクトに変換します |
| finalize_request(ctx, rv) | 最終処理:make_response と after_request フックを呼び出します |
| process_response(ctx, response) | レスポンス後処理:after_request 関数の実行と Session の保存を行います |
| full_dispatch_request(ctx) | 完全なリクエストディスパッチの入口:preprocess → dispatch → finalize |
| handle_http_exception(ctx, e) | HTTP 例外を処理し、対応する errorhandler を検索します |
| handle_user_exception(ctx, e) | ユーザーコードの例外を処理し、HTTP 例外と通常の例外を区別します |
| handle_exception(ctx, e) | 最終的な例外処理。500 レスポンスを返します |
| ensure_sync(func) | 関数が同期実行されることを保証します。async関数は同期にラップされます |
| make_default_options_response(ctx) | 自動的なOPTIONSレスポンスを生成します |
| raise_routing_exception(request) | ルーティング例外を処理します(例: 末尾スラッシュのリダイレクト) |
テンプレートと静的ファイル
| メソッド | 説明 |
|---|---|
| create_jinja_environment() | Jinja2環境を作成して設定します。jinja_envに初めてアクセスしたときに自動的に呼び出されます |
| create_global_jinja_loader() | Jinja2のグローバルローダーを作成し、アプリとブループリントのテンプレート配信をサポートします |
| select_jinja_autoescape(filename) | 指定されたファイルに自動エスケープが必要かどうかを判断します。デフォルトでは .html/.htm/.xml/.xhtml/.svg は True を返します |
| update_template_context(ctx, context) | テンプレートコンテキストに request、session、g、config などの組み込み変数を注入します |
| send_static_file(filename) | static_folder からファイルを送信し、自動的に /static/ として登録します |
| get_send_file_max_age(filename) | 静的ファイルのキャッシュ時間を取得します。デフォルトでは SEND_FILE_MAX_AGE_DEFAULT 設定を使用します |
| open_resource(resource, mode="rb") | root_path 配下のリソースファイルをバイナリモードで開きます |
| open_instance_resource(resource, mode="rb") | instance_path 配下のリソースファイルを開きます。書き込みモードをサポートします |
コンテキスト管理
| メソッド | 説明 |
|---|---|
| app_context() | アプリケーションコンテキストを作成し、with 文で手動でプッシュします。current_app と g を利用可能にします |
| request_context(environ) | WSGI environ に基づいてリクエストコンテキストを作成します |
| test_request_context(*args, **kwargs) | テスト用の模擬リクエストコンテキストを作成します。path、method、data、json などのパラメータを受け取ります |
| wsgi_app(environ, start_response) | コアWSGIアプリケーションメソッド。app.wsgi_app = Middleware(app.wsgi_app) でミドルウェアをラップできます |
テストおよび開発ツール
| メソッド | 説明 |
|---|---|
| test_client(use_cookies=True, **kwargs) | テストクライアントを作成し、ブラウザのリクエスト送信をシミュレートします。FlaskClient インスタンスを返します |
| test_cli_runner(**kwargs) | カスタムコマンドをテストするためのCLIテストランナーを作成します。FlaskCliRunner インスタンスを返します |
| run(host, port, debug, load_dotenv, **options) | 開発サーバーを起動します。本番環境では Gunicorn/Waitress を使用してください |
| make_shell_context() | flask shell のコンテキスト辞書を構築します。すべての shell_context_processor を実行します |
| log_exception(ctx, exc_info) | 例外を logger に記録し、exc_info タプルを渡します |
ユーティリティメソッド
| メソッド | 説明 |
|---|---|
| redirect(location, code=303) | リダイレクトレスポンスオブジェクトを作成します |
| async_to_sync(func) | 非同期コルーチン関数を同期関数に変換します |
| create_url_adapter(request) | リクエストまたは設定に基づいてURLアダプターを作成し、URL構築に使用します |
| inject_url_defaults(endpoint, values) | URL構築プロセスにデフォルトパラメータを注入します |
| handle_url_build_error(error, endpoint, values) | url_for の構築失敗を処理し、代替URLを返すことができます |
| make_config(instance_relative) | Config インスタンスを作成します。サブクラスでオーバーライドして設定をカスタマイズできます |
| make_aborter() | Aborter インスタンスを作成します |
| trap_http_exception(e) | HTTP例外を通常の例外として上位にスローするかどうかを判断します |
| auto_find_instance_path() | instance フォルダのパスを自動的に検索します |
コード例
例
from flask import Flask
# アプリを作成し、テンプレートと静的フォルダを指定します
app = Flask(__name__,
template_folder="templates",
static_folder="static",
instance_relative_config=True)
# シークレットキーを設定します
app.secret_key = "your-secret-key"
# ルートを登録します
@app.route("/")
def index():
return "<h1>Hello, サンプル!</h1>"
# before_request フックを登録します
@app.before_request
def check_auth():
# ここでユーザーの認証状態を確認します
pass
# after_request フックを登録します
@app.after_request
def add_header(response):
# 各レスポンスにカスタムヘッダーを追加します
response.headers["X-Custom-Header"] = "サンプル"
return response
# エラーハンドラーを登録します
@app.errorhandler(404)
def not_found(error):
return "<h1>ページが見つかりません</h1>", 404
# カスタムCLIコマンドを登録します
@app.cli.command("hello")
def hello_command():
"""挨拶を出力します"""
print("Hello from サンプル Flask App!")
# アプリを作成し、テンプレートと静的フォルダを指定します
app = Flask(__name__,
template_folder="templates",
static_folder="static",
instance_relative_config=True)
# シークレットキーを設定します
app.secret_key = "your-secret-key"
# ルートを登録します
@app.route("/")
def index():
return "<h1>Hello, サンプル!</h1>"
# before_request フックを登録します
@app.before_request
def check_auth():
# ここでユーザーの認証状態を確認します
pass
# after_request フックを登録します
@app.after_request
def add_header(response):
# 各レスポンスにカスタムヘッダーを追加します
response.headers["X-Custom-Header"] = "サンプル"
return response
# エラーハンドラーを登録します
@app.errorhandler(404)
def not_found(error):
return "<h1>ページが見つかりません</h1>", 404
# カスタムCLIコマンドを登録します
@app.cli.command("hello")
def hello_command():
"""挨拶を出力します"""
print("Hello from サンプル Flask App!")