API

ドキュメントのこの部分は、Flaskのすべてのインターフェースをカバーしています。 Flaskが外部ライブラリに依存している部分については、ここで最も重要なドキュメントを作成し、正規のドキュメントへのリンクを提供します。

アプリケーションオブジェクト

ブループリントオブジェクト

着信リクエストデータ

flask.request

着信リクエストデータにアクセスするには、グローバル request オブジェクトを使用できます。 Flaskは受信リクエストデータを解析し、そのグローバルオブジェクトを介してアクセスできるようにします。内部的にFlaskは、マルチスレッド環境にいる場合、アクティブなスレッドの正しいデータを常に取得できるようにします。

これはプロキシです。詳細については、プロキシに関する注意事項を参照してください。

リクエストオブジェクトはRequestサブクラスのインスタンスであり、Werkzeugが定義するすべての属性を提供します。これは、最も重要なものの概要を示しています。

応答オブジェクト

セッション

Flask.secret_keyを設定した場合（または SECRET_KEY から構成した場合）、Flaskアプリケーションでセッションを使用できます。セッションを使用すると、ある要求から別の要求への情報を記憶することができます。 Flaskがこれを行う方法は、署名されたCookieを使用することです。ユーザーはセッションの内容を確認できますが、秘密鍵を知らない限り変更できないため、複雑で推測できないものに設定してください。

現在のセッションにアクセスするには、 session オブジェクトを使用できます。

class flask.session

セッションオブジェクトは通常のdictとほとんど同じように機能しますが、変更を追跡するという違いがあります。

これはプロキシです。詳細については、プロキシに関する注意事項を参照してください。

次の属性は興味深いものです。

new: セッションが新しい場合はTrue、それ以外の場合はFalse。

modified

Trueセッションオブジェクトが変更を検出した場合。可変構造の変更は自動的に取得されないことに注意してください。その場合、属性をTrueに明示的に設定する必要があります。ここに例があります：

# this change is not picked up because a mutable object (here
# a list) is changed.
session['objects'].append(42)
# so mark it as modified yourself
session.modified = True

permanent: Trueに設定すると、セッションはpermanent_session_lifetime秒間存続します。デフォルトは31日です。 False（デフォルト）に設定されている場合、ユーザーがブラウザーを閉じるとセッションが削除されます。

セッションインターフェース

バージョン0.8の新機能。

セッションインターフェイスは、Flaskが使用しているセッション実装を置き換える簡単な方法を提供します。

知らせ

PERMANENT_SESSION_LIFETIME構成キーは、Flask0.8以降の整数にすることもできます。これを自分で把握するか、アプリでpermanent_session_lifetime属性を使用して、結果を自動的に整数に変換します。

テストクライアント

CLIランナーのテスト

アプリケーショングローバル

ある関数から別の関数への1つの要求に対してのみ有効なデータを共有するには、スレッド環境で破損するため、グローバル変数は十分ではありません。 Flaskは、アクティブなリクエストに対してのみ有効であり、リクエストごとに異なる値を返すことを保証する特別なオブジェクトを提供します。一言で言えば、リクエストやセッションの場合と同様に、正しいことを行います。

flask.g

アプリケーションコンテキスト中にデータを格納できる名前空間オブジェクト。これはFlask.app_ctx_globals_classのインスタンスであり、デフォルトはctx._AppCtxGlobalsです。

これは、リクエスト中にリソースを保存するのに適した場所です。テスト中に、 Faking Resources and Context パターンを使用して、そのようなリソースを事前構成できます。

これはプロキシです。詳細については、プロキシに関する注意事項を参照してください。

バージョン0.10で変更：リクエストコンテキストではなくアプリケーションコンテキストにバインドされました。

便利な関数とクラス

flask.current_app

現在のリクエストを処理するアプリケーションへのプロキシ。これは、アプリケーションをインポートせずにアプリケーションにアクセスする場合や、アプリケーションのファクトリパターンを使用する場合やブループリントや拡張機能を使用する場合など、インポートできない場合に便利です。

これは、アプリケーションコンテキストがプッシュされた場合にのみ使用できます。これは、要求およびCLIコマンド中に自動的に発生します。 app_context()で手動で制御できます。

これはプロキシです。詳細については、プロキシに関する注意事項を参照してください。

メッセージの点滅

JSONサポート

Flaskは、JSONの実装にsimplejsonを使用します。 simplejsonは標準ライブラリと拡張機能の両方で提供されるため、Flaskは最初にsimplejsonを試し、次にstdlibjsonモジュールにフォールバックします。さらに、現在のアプリケーションのJSONエンコーダーとデコーダーへのアクセスを委任して、カスタマイズを容易にします。

したがって、初心者の場合は、次のことを行う代わりに：

try:
    import simplejson as json
except ImportError:
    import json

代わりに、これを行うことができます。

from flask import json

使用例については、標準ライブラリのjsonのドキュメントをお読みください。次の拡張機能は、デフォルトでstdlibのJSONモジュールに適用されます。

datetimeオブジェクトは、 RFC 822 文字列としてシリアル化されます。
__html__メソッドを持つオブジェクト（Markupなど）では、そのメソッドが呼び出され、戻り値が文字列としてシリアル化されます。

このjsonモジュールのhtmlsafe_dumps()関数は、Jinja2では|tojsonと呼ばれるフィルターとしても使用できます。 Flask 0.10より前のバージョンのFlaskでは、scriptタグ内で|tojson出力を使用する場合は、|safeでのエスケープを無効にする必要があることに注意してください。 Flask 0.10以降では、これは自動的に行われます（ただし、|safeを含めることは無害です）。

<script type=text/javascript>
    doSomethingWith({{ user.username|tojson|safe }});
</script>

JSONキーの自動ソート

構成変数JSON_SORT_KEYS（構成処理）をfalseに設定して、Flaskによるキーの自動ソートを停止できます。デフォルトでは、並べ替えは有効になっており、アプリのコンテキスト外では並べ替えがオンになっています。

キーの並べ替えを無効にすると、コンテンツベースのHTTPキャッシュとPythonのハッシュランダム化機能を使用するときに問題が発生する可能性があることに注意してください。

テンプレートレンダリング

設定

ストリームヘルパー

便利な内部

flask._request_ctx_stack

RequestContextインスタンスを保持する内部LocalStack。通常、スタックの代わりに request および session プロキシにアクセスする必要があります。拡張コードでスタックにアクセスすると便利な場合があります。

次の属性は、スタックの各レイヤーに常に存在します。

アプリ: アクティブなFlaskアプリケーション。
url_adapter: リクエストの照合に使用されたURLアダプター。
リクエスト: 現在のリクエストオブジェクト。
セッション: アクティブなセッションオブジェクト。
g: flask.g オブジェクトのすべての属性を持つオブジェクト。
点滅: フラッシュされたメッセージの内部キャッシュ。

使用例：

from flask import _request_ctx_stack

def get_session():
    ctx = _request_ctx_stack.top
    if ctx is not None:
        return ctx.session

flask._app_ctx_stack: AppContextインスタンスを保持する内部LocalStack。通常、スタックの代わりに current_app および g プロキシにアクセスする必要があります。拡張機能は、データを格納するための名前空間としてスタック上のコンテキストにアクセスできます。

バージョン0.9の新機能。

信号

バージョン0.6の新機能。

signals.signals_available: True信号システムが利用可能な場合。これは、点滅剤が取り付けられている場合です。

Flaskには次の信号があります。

flask.template_rendered

このシグナルは、テンプレートが正常にレンダリングされたときに送信されます。シグナルは、テンプレートのインスタンスを template として、コンテキストをディクショナリ（ context という名前）として呼び出されます。

サブスクライバーの例：

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import template_rendered
template_rendered.connect(log_template_renders, app)

flask.before_render_template

この信号は、テンプレートのレンダリングプロセスの前に送信されます。シグナルは、テンプレートのインスタンスを template として、コンテキストをディクショナリ（ context という名前）として呼び出されます。

サブスクライバーの例：

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import before_render_template
before_render_template.connect(log_template_renders, app)

flask.request_started

このシグナルは、リクエストコンテキストが設定されると、リクエスト処理が行われる前に送信されます。リクエストコンテキストはすでにバインドされているため、サブスクライバーは request などの標準のグローバルプロキシを使用してリクエストにアクセスできます。

サブスクライバーの例：

def log_request(sender, **extra):
    sender.logger.debug('Request context is set up')

from flask import request_started
request_started.connect(log_request, app)

flask.request_finished

このシグナルは、応答がクライアントに送信される直前に送信されます。 response という名前で送信される応答が渡されます。

サブスクライバーの例：

def log_response(sender, response, **extra):
    sender.logger.debug('Request context is about to close down.  '
                        'Response: %s', response)

from flask import request_finished
request_finished.connect(log_response, app)

flask.got_request_exception

このシグナルは、リクエスト処理中に例外が発生したときに送信されます。標準の例外処理が開始される前に送信され、例外処理が行われないデバッグモードでも送信されます。例外自体は、例外としてサブスクライバーに渡されます。

サブスクライバーの例：

def log_exception(sender, exception, **extra):
    sender.logger.debug('Got exception during processing: %s', exception)

from flask import got_request_exception
got_request_exception.connect(log_exception, app)

flask.request_tearing_down

このシグナルは、リクエストが破棄されるときに送信されます。これは、例外が発生した場合でも常に呼び出されます。現在、このシグナルをリッスンする関数は、通常のティアダウンハンドラーの後に呼び出されますが、これは信頼できるものではありません。

サブスクライバーの例：

def close_db_connection(sender, **extra):
    session.close()

from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)

Flask 0.9以降、これには exc キーワード引数も渡されます。この引数には、ティアダウンが発生した場合に発生した例外への参照が含まれます。

flask.appcontext_tearing_down

このシグナルは、アプリのコンテキストが破棄されているときに送信されます。これは、例外が発生した場合でも常に呼び出されます。現在、このシグナルをリッスンする関数は、通常のティアダウンハンドラーの後に呼び出されますが、これは信頼できるものではありません。

サブスクライバーの例：

def close_db_connection(sender, **extra):
    session.close()

from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)

これには、 exc キーワード引数も渡されます。この引数には、ティアダウンが発生した場合に発生した例外への参照が含まれています。

flask.appcontext_pushed

このシグナルは、アプリケーションコンテキストがプッシュされたときに送信されます。送信者はアプリケーションです。これは通常、情報を一時的にフックするためのユニットテストに役立ちます。たとえば、 g オブジェクトにリソースを早期に設定するために使用できます。

使用例：

from contextlib import contextmanager
from flask import appcontext_pushed

@contextmanager
def user_set(app, user):
    def handler(sender, **kwargs):
        g.user = user
    with appcontext_pushed.connected_to(handler, app):
        yield

そしてテストコードでは：

def test_user_me(self):
    with user_set(app, 'john'):
        c = app.test_client()
        resp = c.get('/users/me')
        assert resp.data == 'username=john'

バージョン0.10の新機能。

flask.appcontext_popped: このシグナルは、アプリケーションコンテキストがポップされたときに送信されます。送信者はアプリケーションです。これは通常、 appcontext_tearing_down 信号と一致します。

バージョン0.10の新機能。

flask.message_flashed

この信号は、アプリケーションがメッセージをフラッシュしているときに送信されます。メッセージはメッセージキーワード引数として送信され、カテゴリはカテゴリとして送信されます。

サブスクライバーの例：

recorded = []
def record(sender, message, category, **extra):
    recorded.append((message, category))

from flask import message_flashed
message_flashed.connect(record, app)

バージョン0.10の新機能。

class signals.Namespace: ブリンカーが使用可能な場合はblinker.base.Namespaceのエイリアス、それ以外の場合は偽の信号を作成するダミークラス。このクラスは、Flask自体と同じフォールバックシステムを提供したいFlask拡張機能で使用できます。

signal(name, doc=None) ブリンカーが使用可能な場合は、この名前空間の新しいシグナルを作成します。それ以外の場合は、接続を含む他のすべての操作でRuntimeErrorで失敗するだけのsendメソッドを持つ偽のシグナルを返します。

クラスベースのビュー

バージョン0.7の新機能。

URLルート登録

一般に、ルーティングシステムのルールを定義する方法は3つあります。

flask.Flask.route()デコレータを使用できます。
flask.Flask.add_url_rule()機能を使用できます。
flask.Flask.url_mapとして公開されている基盤となるWerkzeugルーティングシステムに直接アクセスできます。

ルート内の可変パーツは、山括弧（/user/<username>）で指定できます。デフォルトでは、URLの可変部分はスラッシュなしの任意の文字列を受け入れますが、<converter:name>を使用して別のコンバーターを指定することもできます。

可変部分は、キーワード引数としてビュー関数に渡されます。

次のコンバーターが使用可能です。

ストリング	スラッシュなしのテキストを受け入れます（デフォルト）
int	整数を受け入れます
浮く	int と似ていますが、浮動小数点値用です
道	デフォルトと同様ですが、スラッシュも受け入れます
どれか	提供されたアイテムの1つと一致します
uuid	UUID文字列を受け入れます

カスタムコンバーターは、flask.Flask.url_mapを使用して定義できます。

ここではいくつかの例を示します。

@app.route('/')
def index():
    pass

@app.route('/<username>')
def show_user(username):
    pass

@app.route('/post/<int:post_id>')
def show_post(post_id):
    pass

覚えておくべき重要な詳細は、Flaskが末尾のスラッシュをどのように処理するかです。次のルールが適用されるように、各URLを一意に保つという考え方です。

ルールがスラッシュで終了し、ユーザーがスラッシュなしで要求した場合、ユーザーは、末尾にスラッシュが付いた同じページに自動的にリダイレクトされます。
ルールが末尾のスラッシュで終了せず、ユーザーが末尾のスラッシュでページを要求した場合、404 notfoundが発生します。

これは、Webサーバーが静的ファイルを処理する方法と一致しています。これにより、相対リンクターゲットを安全に使用することもできます。

同じ関数に対して複数のルールを定義することもできます。ただし、それらは一意である必要があります。デフォルトも指定できます。たとえば、オプションのページを受け入れるURLの定義は次のとおりです。

@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
    pass

これは、/users/がページ1のURLになり、/users/page/NがページNのURLになることを指定します。

URLにデフォルト値が含まれている場合、301リダイレクトを使用してより単純な形式にリダイレクトされます。上記の例では、/users/page/1は/users/にリダイレクトされます。ルートがGETおよびPOSTリクエストを処理する場合、リダイレクトではフォームデータを保持できないため、デフォルトルートがGETのみを処理することを確認してください。

@app.route('/region/', defaults={'id': 1})
@app.route('/region/<int:id>', methods=['GET', 'POST'])
def region(id):
   pass

route()およびadd_url_rule()が受け入れるパラメーターは次のとおりです。唯一の違いは、routeパラメーターでは、view関数が view_func パラメーターではなくデコレーターで定義されていることです。

ルール	文字列としてのURLルール
終点	登録されたURLルールのエンドポイント。 Flask自体は、明示的に指定されていない限り、ビュー関数の名前がエンドポイントの名前であると想定します。
view_func	提供されたエンドポイントにリクエストを提供するときに呼び出す関数。これが提供されていない場合は、エンドポイントをキーとして`view_functions`ディクショナリに保存することにより、後で関数を指定できます。
デフォルト	このルールのデフォルトの辞書。デフォルトの仕組みについては、上記の例を参照してください。
サブドメイン	サブドメインマッチングが使用されている場合のサブドメインのルールを指定します。指定しない場合、デフォルトのサブドメインが想定されます。
**オプション	基になる`Rule`オブジェクトに転送されるオプション。 Werkzeugへの変更は、メソッドオプションの処理です。メソッドは、このルールを制限する必要があるメソッドのリストです（`GET`、`POST`など）。デフォルトでは、ルールは`GET`（および暗黙的に`HEAD`）をリッスンします。 Flask 0.6以降、`OPTIONS`は暗黙的に追加され、標準のリクエスト処理によって処理されます。キーワード引数として指定する必要があります。

機能オプションの表示

内部で使用する場合、ビュー関数には、通常はビュー関数が制御できない動作をカスタマイズするための属性をいくつか付けることができます。次の属性をオプションで指定して、add_url_rule()のデフォルトまたは一般的な動作をオーバーライドできます。

__ name __ ：関数の名前は、デフォルトでエンドポイントとして使用されます。エンドポイントが明示的に指定されている場合、この値が使用されます。さらに、これにはデフォルトでブループリントの名前が接頭辞として付けられますが、関数自体からカスタマイズすることはできません。
methods ：URLルールの追加時にメソッドが指定されていない場合、 methods 属性が存在する場合、Flaskはビュー関数オブジェクト自体を調べます。含まれている場合は、そこからメソッドの情報を取得します。
Provide_automatic_options ：この属性が設定されている場合、FlaskはHTTP OPTIONS応答の自動実装を強制的に有効または無効にします。これは、ビューごとにOPTIONS応答をカスタマイズするデコレータを操作するときに役立ちます。
required_methods ：この属性が設定されている場合、route()呼び出しでメソッドが明示的にオーバーライドされた場合でも、FlaskはURLルールの登録時にこれらのメソッドを常に追加します。

完全な例：

def index():
    if request.method == 'OPTIONS':
        # custom options handling here
        ...
    return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']

app.add_url_rule('/', index)

バージョン0.8の新機能： Provide_automatic_options 機能が追加されました。

コマンドラインインターフェイス

API —フラスコのドキュメント

目次

API

アプリケーションオブジェクト

ブループリントオブジェクト

着信リクエストデータ

応答オブジェクト

セッション

セッションインターフェース

テストクライアント

CLIランナーのテスト

アプリケーショングローバル

便利な関数とクラス

メッセージの点滅

JSONサポート

テンプレートレンダリング

設定

ストリームヘルパー

便利な内部

信号

クラスベースのビュー

URLルート登録

機能オプションの表示

コマンドラインインターフェイス