Skip to content

Flask Шпаргалка

Лёгкий веб-фреймворк Python (микрофреймворк).

01

Начало работы

Первое приложение

Flask — микрофреймворк: он даёт необходимое и позволяет добавлять то, что нужно. debug=True включает автоперезагрузку и подробные страницы ошибок.

flask
# 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)

Запуск сервера разработки

Никогда не используйте встроенный сервер в production. FLASK_APP указывает на модуль с экземпляром приложения. --host=0.0.0.0 делает его доступным по сети.

flask
# 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.

flask
# 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/ хранит секреты конкретного развёртывания, которые не должны попадать в систему контроля версий.

flask
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

Паттерн фабрики приложений

Фабричный паттерн откладывает создание приложения до вызова функции, что необходимо для нескольких экземпляров, тестирования и расширений. Опция --app в Flask принимает вызываемый объект, возвращающий приложение.

flask
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, где искать статические файлы и шаблоны. Расположение папок можно переопределить аргументами конструктора, если ваша структура отличается от стандартной.

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!"
02

Маршрутизация

Правила с переменными

Сегменты вида <converter:varname> захватывают части URL. Встроенные конвертеры: string (по умолчанию), int, float, path (принимает слэши), uuid. Значение передаётся аргументом функции.

flask
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. Зарегистрируйте свой подкласс BaseConverter в app.url_map.converters, чтобы задать регулярное выражение, например для кодов товаров.

flask
@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 для варианта со слэшем. Выберите одно соглашение для маршрута и придерживайтесь его.

flask
@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 Found

HTTP-методы

Аргумент methods принимает несколько глаголов, а сокращения @app.get / @app.post (Flask 2.0+) задают маршрут для одного метода. GET используется по умолчанию.

flask
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 через url_for

url_for строит URL по имени endpoint (по умолчанию — имя функции-обработчика). Он переживает изменения URL, а при _external=True выдаёт абсолютный URL.

flask
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/bob

Несколько правил для одного обработчика

add_url_rule регистрирует URL без декоратора. Задавая каждому правилу отдельный endpoint, но одну и ту же функцию с defaults, один обработчик обслуживает несколько форм URL.

flask
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.
03

Запрос и ответ

Объект request

request — потоково-локальный прокси, привязанный к контексту текущего запроса. Он даёт доступ к URL, методу, заголовкам, телу и данным клиента без явной передачи.

flask
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) или кортеж (тело, статус, заголовки).

flask
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

Используйте Response, когда нужен свой mimetype (например, XML, CSV) или заголовки. Заголовок Content-Disposition: attachment заставляет браузер скачать файл.

flask
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)

Свой статус и заголовки

Возвращайте кортеж (тело, статус, заголовки) для кратких своих ответов. Используйте 204 No Content для успешных ответов без тела и стандартные HTTP-коды для семантики.

flask
@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.

flask
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 делает cookie истёкшим. Всегда задавайте httponly и samesite для безопасности. Cookie — часть ответа, а не тела запроса.

flask
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 resp
04

Объект request (form/args/files)

Query-параметры (args)

request.args — MultiDict значений строки запроса. Используйте get со значением по умолчанию и преобразованием типа, а для повторяющихся ключей — getlist. Не обращайтесь по индексу: отсутствующий ключ даёт 400.

flask
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. Используйте .get(), чтобы избежать KeyError на необязательных полях. У GET-запросов форма пустая.

flask
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 — MultiDict объектов FileStorage. Всегда пропускайте имена файлов от пользователя через secure_filename, чтобы убрать разделители путей и опасные символы перед сохранением.

flask
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() разбирает тело как JSON только при Content-Type application/json. force=True игнорирует заголовок (осторожно). silent=True подавляет ошибки разбора.

flask
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 задавайте в ответе.

flask
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 — сырые байты после '?'.

flask
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(),
    }
05

Шаблоны Jinja2

Рендеринг шаблонов

render_template загружает файл Jinja2 из папки templates/ и передаёт именованные аргументы как переменные. Синтаксис {{ }} выводит выражение; Flask автоматически экранирует HTML для безопасности.

flask
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 помечает строку как доверенную, чтобы её не экранировали, — применяйте только к содержимому, которое полностью контролируете.

flask
# 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 выполняется, когда итерируемое пусто.

flask
{# 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 подключает базовый шаблон, а дочерние переопределяют именованные блоки. Так общая вёрстка (навигация, скрипты) хранится в одном месте. super() выводит содержимое родительского блока.

flask
{# 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, чтобы переиспользовать логику в шаблонах.

flask
{{ 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 (поля форм, карточки).

flask
{# 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>
06

Статические файлы

Отдача статических файлов

Flask автоматически регистрирует маршрут /static/<path:filename> для папки static. Всегда стройте URL через url_for, чтобы пути оставались корректными даже при изменении static_url_path.

flask
# 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=...) строит путь к статическому файлу. Передайте _external=True для абсолютного URL (нужно в письмах и фидах) и query-аргументы для сброса кеша.

flask
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.

flask
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.css

Favicon

Браузеры по умолчанию запрашивают /favicon.ico в корне. Добавьте явный маршрут или подключите иконку через тег <link>. send_from_directory безопасно отдаёт файл из каталога.

flask
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).

flask
# 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 }}">
07

Blueprint

Создание blueprint

Blueprint группирует связанные маршруты, шаблоны и статические файлы в модуль. Первый аргумент — имя blueprint; url_prefix добавляет префикс ко всем его маршрутам.

flask
# 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 монтируется по разным путям в разных приложениях.

flask
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")

Blueprint с префиксом URL

Задавайте url_prefix в Blueprint или при регистрации. Версионирование пути API (/api/v1) позволяет позже добавить /api/v2, не ломая существующих клиентов.

flask
# 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 перекрывают одноимённые общие.

flask
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 ловят только ошибки его маршрутов, давая разделу свои страницы ошибок. Обработчики уровня приложения берут всё непойманное.

flask
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. Зарегистрируйте дочерний blueprint на родительском через register_blueprint: их url_prefix объединяются, позволяя собирать большие приложения из малых модулей.

flask
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
08

Контекст (g / session)

Контекст приложения

Контекст приложения делает current_app и g доступными вне запроса (например, в CLI-командах или фоновых задачах). Вне запроса его нужно активировать через app.app_context().

flask
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.

flask
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 к потоку. Используйте test_request_context в тестах и скриптах, чтобы имитировать запрос без HTTP-сервера.

flask
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, которые передают доступ к атрибутам активному контексту. Никогда не сохраняйте их в глобальную переменную — обращайтесь к ним во время вызова.

flask
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. Задайте app.secret_key, чтобы Flask мог его подписывать. Значения хранятся на клиенте и читаются пользователем (но не подделываются), поэтому не храните там секреты.

flask
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_* выполняются всегда, даже при ошибках, поэтому именно там закрывают подключения к БД и освобождают ресурсы.

flask
# 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)
09

Интеграция SQLAlchemy

Настройка Flask-SQLAlchemy

Flask-SQLAlchemy оборачивает SQLAlchemy и интегрирует её с контекстом приложения Flask. Задайте SQLALCHEMY_DATABASE_URI строкой подключения и отключите отслеживание изменений ради экономии памяти.

flask
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 для ограничений.

flask
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() возвращает элементы и метаданные страницы.

flask
# 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(), чтобы сессия осталась рабочей.

flask
# 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' возвращает объект запроса вместо списка — удобно для больших коллекций, которые нужно дополнительно фильтровать.

flask
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 user

Миграции с Flask-Migrate

Flask-Migrate оборачивает Alembic для версионирования схемы. Запустите migrate, чтобы сгенерировать скрипт по изменениям моделей, затем upgrade, чтобы применить его. Всегда просматривайте автогенерированные скрипты перед коммитом.

flask
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 revision
10

WTForms (Flask-WTF)

Установка Flask-WTF

Flask-WTF интегрирует WTForms с Flask и автоматически добавляет защиту CSRF. Нужен SECRET_KEY, чтобы подписать CSRF-токен. Отключайте CSRF только для публичных API-endpoint.

flask
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(). Валидаторы проверяют обязательность, длину, формат email и другое.

flask
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-токен и скрытые поля. Каждое поле может отдельно выводить подпись, input и ошибки. Для быстрого вывода {{ form.field() }} рендерит HTML-поле.

flask
{# 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() возвращает True только для POST-запроса, где все валидаторы прошли. При успехе читайте значения из form.field.data. При ошибке перерендерите шаблон, чтобы показать ошибки.

flask
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 часто используют для подтверждения пароля. Объединяйте их в список: они выполняются по порядку до первой ошибки.

flask
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

Используйте FileField из flask_wtf.file с FileRequired и FileAllowed для проверки загрузок. Загруженный файл — объект FileStorage в form.field.data. Тег формы должен включать enctype=multipart/form-data.

flask
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)
11

Аутентификация Flask-Login

Настройка Flask-Login

Flask-Login управляет сессиями пользователей: вход, выход и запоминание. Задайте login_view, куда перенаправляются неаутентифицированные пользователи. login_message показывается при этом редиректе.

flask
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."

Модель пользователя

Модель пользователя должна подмешивать UserMixin (даёт is_authenticated, is_active, get_id и др.) и реализовывать колбэк user_loader, возвращающий пользователя по ID. Никогда не храните пароли в открытом виде — хешируйте их.

flask
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 загружает пользователя в сессию. Передайте remember=True для постоянных cookie. Всегда проверяйте пароль по хешу перед входом и показывайте общее сообщение об ошибке при неудаче.

flask
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), доступный в обработчиках и шаблонах.

flask
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, чтобы выходить могли только вошедшие. После выхода перенаправьте на публичную страницу (главную или вход).

flask
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 cookies

Remember me и current_user

remember=True ставит отдельный cookie, чтобы пользователь оставался в системе после закрытия браузера. current_user работает и в обработчиках, и в шаблонах, позволяя условно рендерить интерфейс по статусу аутентификации.

flask
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 %}
12

Обработка ошибок

abort()

abort() немедленно прерывает обработчик и возвращает HTTP-ошибку. Передайте код состояния и необязательное сообщение. Он бросает HTTPException, который Flask превращает в соответствующий ответ с ошибкой.

flask
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). Возвращайте кортеж (шаблон, status_code). Эти обработчики ловят и вызовы abort(), и исключения, соответствующие этому коду.

flask
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-кодов. Бросок исключения в любом месте обработчика вызывает обработчик, централизуя ответы на ошибки предметной области.

flask
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)

Общий обработчик 404

Общий обработчик Exception — крайняя мера для 500. Повторно бросайте HTTPException, чтобы встроенные страницы продолжали работать, и логируйте трассировку. Не допускайте утечки трассировок пользователям в production.

flask
@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 не даёт лог-файлам расти без предела. В production направляйте логи в централизованный сервис.

flask
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", 500

Обработка HTTP-исключений

HTTPException — базовый класс всех HTTP-ошибок Werkzeug. Обработчик для HTTPException ловит их все сразу, а обработчик для конкретного подкласса (NotFound) имеет приоритет для этого кода.

flask
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", 404
13

JSON и API

jsonify

jsonify превращает словари и списки Python в JSON-ответ с правильным Content-Type и ASCII-безопасным экранированием. С Flask 2.1+ можно передавать список напрямую; в старых версиях нужен словарь.

flask
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 escaping

Возврат JSON

Возврат словаря или списка напрямую — простейший способ отправить JSON. Для своих кодов состояния или заголовков верните кортеж. Response + json.dumps нужны только для полного контроля над сериализацией.

flask
# 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() разбирает тело как JSON при Content-Type application/json. Всегда проверяйте разобранную структуру перед использованием: не доверяйте вводу клиента. Возвращайте 400/422 на некорректные данные.

flask
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"]}), 201

Blueprint для API

Группируйте маршруты API в blueprint с версионированным url_prefix (/api/v1). Это отделяет API от страничных маршрутов и делает версионирование явным: переходите на /api/v2 при ломающих изменениях.

flask
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, чтобы браузеры разрешали межсайтовые запросы. В production ограничьте источники доверенными доменами вместо шаблона '*'.

flask
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

Вспомогательная функция делает ответы с ошибками единообразными: одна форма, одни имена ключей. Единообразные тела ошибок сильно упрощают обработку на клиенте. Включайте детали, помогающие отладке, но не раскрывайте секреты.

flask
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}
14

Загрузка файлов

Базовая загрузка

Тег формы должен иметь enctype=multipart/form-data для загрузки файлов. Задайте MAX_CONTENT_LENGTH, чтобы отклонять слишком большие загрузки с кодом 413 до полного чтения тела — это защищает сервер.

flask
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 убирает из имён файлов пользователя path traversal и опасные символы. Он не гарантирует уникальность: добавляйте UUID или проверяйте коллизии, если перезапись опасна.

flask
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}"

Несколько файлов

Используйте request.files.getlist('files') с input, имеющим атрибут multiple, чтобы принять несколько файлов сразу. Проверяйте расширение и размер каждого файла перед сохранением.

flask
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

FileField из Flask-WTF проверяет расширение и наличие загрузки. Тег формы должен включать enctype=multipart/form-data. Загруженный файл доступен в form.photo.data.

flask
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 рано отклоняет огромные запросы, но проверки по каждому файлу дают более тонкий контроль. Для надёжности смотрите magic bytes, а не только расширение.

flask
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"
15

Cookie и сессии

Установка cookie

Cookie задаются на объекте ответа через set_cookie. Ставьте httponly=True, чтобы JavaScript не мог их прочитать (защита от XSS), secure=True для HTTPS-only и samesite='Lax' или 'Strict' для защиты от CSRF.

flask
from flask import make_response

@app.route("/set-cookie")
def set_cookie():
    resp = make_response("cookie set")
    resp.set_cookie("user", "alice", max_age=3600, httponly=True)
    resp.set_cookie("theme", "dark", path="/", secure=True, samesite="Lax")
    return resp

# max_age in seconds; expires sets a datetime
# httponly blocks JS access; secure requires HTTPS
# samesite: "Lax" (default), "Strict", or "None"

Чтение cookie

request.cookies — доступный только для чтения ImmutableMultiDict cookie, отправленных браузером. Используйте .get() со значением по умолчанию вместо индексации: cookie может отсутствовать. Изменение cookie происходит в ответе.

flask
from flask import request

@app.route("/show-cookies")
def show_cookies():
    user = request.cookies.get("user", "guest")
    theme = request.cookies.get("theme", "light")
    all_cookies = request.cookies.to_dict()
    return f"user={user}, theme={theme}"

# request.cookies is a read-only dict
# use .get() with a default to avoid KeyError

Объект session

session — подписанный cookie с сериализованным словарём. Так как он подписан secret_key, пользователь не может его подделать, но МОЖЕТ прочитать — поэтому никогда не храните в сессии пароли и секреты.

flask
from flask import session

app.secret_key = "a-very-secret-string"

@app.route("/login")
def login():
    session["user_id"] = 1
    session["role"] = "admin"
    return "logged in"

@app.route("/dashboard")
def dashboard():
    if "user_id" not in session:
        return "please log in", 401
    return f"user {session['user_id']}"

@app.route("/logout")
def logout():
    session.pop("user_id", None)
    return "logged out"

Secret key

secret_key подписывает cookie сессии и CSRF-токены. Используйте длинное случайное значение и загружайте его из окружения, чтобы не коммитить в репозиторий. Все экземпляры приложения должны использовать один и тот же ключ.

flask
import os
from flask import Flask

app = Flask(__name__)

# Generate a strong random key
app.secret_key = os.urandom(32)

# Or load from environment (recommended for production)
app.secret_key = os.environ.get("SECRET_KEY")

# For multiple workers, all must share the same key
# so sessions survive being routed to different processes.
# A key of at least 32 random bytes is recommended.

Flash-сообщения

flash сохраняет сообщение в сессии, которое переживает редирект и показывается на следующем запросе. Вызовите get_flashed_messages в шаблоне, чтобы получить и очистить их. with_categories позволяет стилизовать по типу.

flask
from flask import flash, redirect, url_for, render_template

app.secret_key = "secret"   # flash uses the session

@app.route("/save", methods=["POST"])
def save():
    flash("Saved successfully!", "success")
    return redirect(url_for("index"))

# In the template:
# {% with messages = get_flashed_messages(with_categories=true) %}
#   {% for category, message in messages %}
#     <div class="alert alert-{{ category }}">{{ message }}</div>
#   {% endfor %}
# {% endwith %}

Настройка сессий

По умолчанию сессии хранятся в cookie и истекают при закрытии браузера. Задайте session.permanent=True и PERMANENT_SESSION_LIFETIME, чтобы продлить их. Flask-Session переносит хранение на сервер (Redis, файловая система) для больших и более защищённых сессий.

flask
app.config.update(
    SECRET_KEY="secret",
    SESSION_COOKIE_NAME="sid",
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,     # HTTPS only
    SESSION_COOKIE_SAMESITE="Lax",
    PERMANENT_SESSION_LIFETIME=3600,  # seconds
    SESSION_TYPE="redis",            # needs Flask-Session
)

# Mark a session as permanent
from flask import session
from datetime import timedelta

@app.route("/remember")
def remember():
    session.permanent = True
    session["user"] = "alice"
    return "remembered for 1 hour"
16

Хуки before/after request

before_request

Обработчики before_request выполняются перед каждым обработчиком. Используйте их для проверки аутентификации, режима обслуживания или загрузки общих данных в g. Возврат значения пропускает обработчик и использует этот ответ напрямую.

flask
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 request

after_request

Обработчики after_request выполняются после обработчика, получая и возвращая ответ. Идеальны для добавления заголовков, логирования и кеширования. При необработанном исключении after_request пропускается.

flask
@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 object

teardown_request

teardown_request выполняется в конце каждого запроса, даже при ошибках, — в отличие от after_request. Он получает исключение (или None) и подходит для освобождения ресурсов вроде подключений к БД и файлов.

flask
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 raised

before_first_request (устарел)

before_first_request удалён во Flask 2.3, так как ломается с современными асинхронными серверами и многопроцессными схемами. Выполняйте разовую настройку в контексте приложения при импорте или в CLI-команде.

flask
# 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 трассировки.

flask
@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. Так каждый запрос получает своё подключение и очистка гарантирована даже при ошибках.

flask
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]}
17

CLI-команды

Свои команды

Используйте @app.cli.command, чтобы зарегистрировать CLI-команду, оформленную аргументами и опциями click. Docstring становится текстом справки. Запустите flask --help, чтобы увидеть все доступные команды.

flask
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 --admin

flask run

flask run запускает сервер разработки Werkzeug. --debug включает перезагрузчик и интерактивный отладчик. --app указывает модуль или фабрику. Никогда не используйте этот сервер в production: он однопоточный и небезопасный.

flask
# 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, чтобы можно было экспериментировать без импортов. Это бесценно для отладки моделей и разовых запросов к приложению.

flask
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, чтобы у них был доступ к настроенному приложению. Опция --app в Flask сама находит фабрику и вызывает её.

flask
# 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 и т. д.

flask
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

Переменные окружения

FLASK_APP и FLASK_DEBUG настраивают CLI. Используйте .flaskenv для общих настроек разработки и .env для секретов (оба загружаются автоматически, если установлен python-dotenv). Держите секреты вне .flaskenv, так как он обычно коммитится.

flask
# 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.
18

Тестирование

Основы тестового клиента

test_client() возвращает клиент, делающий запросы без сети. Установите TESTING=True для лучших сообщений об ошибках и отключения перехвата ошибок. Используйте фикстуру, чтобы каждый тест получал свежее приложение.

flask
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

Запросы в тестах

Тестовый клиент имитирует браузер: get/post/put/delete с data (форма), json, query_string и headers. Используйте resp.get_json() для разбора JSON-ответа и resp.headers для просмотра заголовков.

flask
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=..., чтобы отправить JSON-тело с правильным Content-Type. Проверяйте статус, разобранное JSON-тело и заголовки вроде Location. Тестирование и успешных, и ошибочных путей обеспечивает согласованность API.

flask
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

Фикстуры дают переиспользуемую подготовку: базу в памяти, тестовый клиент и CLI-раннер. Отдавайте ресурс через yield и очищайте после. test_cli_runner() вызывает CLI-команды в тестах и проверяет их вывод и код возврата.

flask
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 в памяти для быстрых изолированных тестов. Создавайте таблицы и данные в фикстуре, затем удаляйте всё после. Каждый тест начинается с чистого состояния, что предотвращает взаимное влияние.

flask
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, почта, очереди) моками, чтобы тесты оставались быстрыми и детерминированными. Проверяйте, что мок вызван с ожидаемыми аргументами. Патчите там, где имя ищется, а не где определено.

flask
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!")
19

Развёртывание

Предупреждение о production-сервере

Сервер разработки Werkzeug однопоточный и небезопасный — никогда не выставляйте его в интернет. Используйте production WSGI-сервер (Gunicorn, uWSGI, Waitress) за обратным прокси. Отладчик debug — риск удалённого выполнения кода.

flask
# 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 — самый популярный WSGI-сервер для Linux/macOS. Формула (2 × CPU + 1) воркеров — хорошая отправная точка. За Nginx привязывайтесь к 127.0.0.1, а TLS и статику отдайте прокси.

flask
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-сервер. Мастер-процесс управляет воркерами; vacuum очищает при выходе. Для лучшей пропускной способности используйте с Nginx по протоколу uwsgi.

flask
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, чтобы им доверять.

flask
# /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), никогда не запекайте их в образ.

flask
# 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

Конфигурация окружения

Слои конфигурации: значения по умолчанию в коде, переопределения под окружение и секреты instance из переменных окружения. Так секреты не попадают в репозиторий, а одна кодовая база работает в dev, staging и production.

flask
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()
20

Конфигурация

Объект конфигурации

Описывайте конфигурацию классами, наследующими базовый Config. Переопределяйте только то, что меняется по окружениям. from_object копирует атрибуты в верхнем регистре в app.config, а строчные помощники игнорируются.

flask
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 загружает файл Python, на который указывает переменная окружения, — удобно для переопределений под развёртывание. python-dotenv загружает .env для локальной разработки.

flask
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. Так код чисто отделяется от конфигурации окружения.

flask
# 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. Выберите один формат и придерживайтесь его.

flask
# 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" }

Разработка против production

Переключайте конфигурации переменной окружения, чтобы один и тот же код работал везде. В production обязательно отключите debug (отладчик — дыра в безопасности) и используйте настоящую базу данных. Логируйте предупреждение, если debug включён в production.

flask
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 не даёт логам расти без предела. В production рассмотрите структурированное JSON-логирование для сервисов агрегации.

flask
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

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.