Начало работы
Первое приложение
Flask — микрофреймворк: он даёт необходимое и позволяет добавлять то, что нужно. debug=True включает автоперезагрузку и подробные страницы ошибок.
# install Flask
pip install flask
# app.py
from flask import Flask, render_template
app = Flask(__name__)
@app.route("/")
def home():
return render_template("index.html")
if __name__ == "__main__":
app.run(debug=True)Запуск сервера разработки
Никогда не используйте встроенный сервер в production. FLASK_APP указывает на модуль с экземпляром приложения. --host=0.0.0.0 делает его доступным по сети.
# Set the entry point and enable debug mode
export FLASK_APP=app.py
export FLASK_ENV=development
flask run
# Override host and port
flask run --host=0.0.0.0 --port=5000
# Or run the module directly
python app.pyВиртуальное окружение
Виртуальное окружение изолирует зависимости проекта от системного Python. requirements.txt фиксирует точные версии, чтобы другие могли воспроизвести окружение командой pip install -r requirements.txt.
# Create an isolated environment
python -m venv venv
# Activate (Linux/macOS)
source venv/bin/activate
# Activate (Windows PowerShell)
venv\Scripts\Activate.ps1
# Install dependencies
pip install flask
pip freeze > requirements.txtСтруктура проекта
Flask не навязывает структуру, но разделение статических файлов, шаблонов и конфигурации — общепринятая практика. Папка instance/ хранит секреты конкретного развёртывания, которые не должны попадать в систему контроля версий.
myapp/
app.py # application factory or instance
config.py # configuration classes
requirements.txt # pinned dependencies
instance/
config.py # secret instance config (not in VCS)
static/ # CSS, JS, images
css/style.css
templates/ # Jinja2 templates
base.html
index.html
models.py # database models
views.py # route handlersПаттерн фабрики приложений
Фабричный паттерн откладывает создание приложения до вызова функции, что необходимо для нескольких экземпляров, тестирования и расширений. Опция --app в 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, где искать статические файлы и шаблоны. Расположение папок можно переопределить аргу ментами конструктора, если ваша структура отличается от стандартной.
from flask import Flask
app = Flask(
__name__,
static_folder="static",
template_folder="templates",
static_url_path="/static",
)
# __name__ lets Flask locate resources relative to the module.
# Route decorators map URL patterns to view functions.
@app.route("/")
def index():
return "Hello, Flask!"Маршрутизация
Правила с переменными
Сегменты вида <converter:varname> захватывают части URL. Встроенные конвертеры: string (по умолчанию), int, float, path (принимает слэши), uuid. Значение передаётся аргументом функции.
from flask import Flask
app = Flask(__name__)
@app.route("/user/<username>")
def show_user(username):
return f"User: {username}"
@app.route("/post/<int:post_id>")
def show_post(post_id):
return f"Post #{post_id}"
@app.route("/path/<path:subpath>")
def show_path(subpath):
return f"Path: {subpath}"Конвертеры URL
Конвертеры проверяют и приводят переменные URL. Зарегистрируйте свой подкласс BaseConverter в app.url_map.converters, чтобы задать регулярное выражение, например для кодов товаров.
@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 для варианта со слэшем. Выберите одно соглашение для маршрута и придерживайтесь его.
@app.route("/projects/")
def projects():
return "Projects page"
# /projects/ -> 200 OK
# /projects -> 301 redirect to /projects/
@app.route("/about")
def about():
return "About page"
# /about -> 200 OK
# /about/ -> 404 Not FoundHTTP-методы
Аргумент methods принимает несколько глаголов, а сокращения @app.get / @app.post (Flask 2.0+) задают маршрут для одного метода. GET используется по умолчанию.
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
return do_login()
return render_template("login.html")
# Method-specific shortcuts
@app.get("/profile")
def profile_get():
return render_template("profile.html")
@app.post("/profile")
def profile_post():
return update_profile()Построение URL через url_for
url_for строит URL по имени endpoint (по умолчанию — имя функции-обработчика). Он переживает изменения URL, а при _external=True выдаёт абсолютный URL.
from flask import Flask, url_for
app = Flask(__name__)
@app.route("/")
def index():
# builds '/user/alice' instead of hardcoding
return f'<a href="{url_for("show_user", username="alice")}">Alice</a>'
@app.route("/user/<username>")
def show_user(username):
return f"Hello {username}"
with app.test_request_context():
print(url_for("show_user", username="bob")) # /user/bobНесколько правил для одного обработчика
add_url_rule регистрирует URL без декоратора. Задавая каждому правилу отдельный endpoint, но одну и ту же функцию с defaults, один обработчик обслуживает несколько форм URL.
from flask import Flask
app = Flask(__name__)
def show(id=None, name=None):
if id is not None:
return f"By id: {id}"
return f"By name: {name}"
app.add_url_rule("/by-id/<int:id>", "by_id", show, defaults={"name": None})
app.add_url_rule("/by-name/<name>", "by_name", show, defaults={"id": None})
# Two endpoints share one function with different defaults.Запрос и ответ
Объект request
request — потоково-локальный прокси, привязанный к контексту текущего запроса. Он даёт доступ к URL, методу, заголовкам, телу и данным клиента без явной передачи.
from flask import Flask, request
app = Flask(__name__)
@app.route("/info")
def info():
return {
"url": request.url,
"method": request.method,
"remote_addr": request.remote_addr,
"user_agent": str(request.user_agent),
"headers": dict(request.headers),
}Создание ответа
make_response даёт полный контроль над статусом, заголовками и телом. В простых случаях возвращайте строку, словарь (JSON) или кортеж (тело, статус, заголовки).
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 заставляет браузер скачать файл.
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-коды для семантики.
@app.route("/created")
def created():
return "done", 201, {"Location": "/resource/1"}
@app.route("/no-content")
def no_content():
return "", 204
@app.route("/teapot")
def teapot():
return "I'm a teapot", 418Потоковые ответы
Возврат генератора передаёт данные клиенту потоком. Полезно для больших файлов (не нужно держать весь файл в памяти) и Server-Sent Events. Задайте подходящий mimetype.
from flask import Response
def generate():
yield "data: first\n\n"
yield "data: second\n\n"
yield "data: third\n\n"
@app.route("/stream")
def stream():
return Response(generate(), mimetype="text/event-stream")
@app.route("/big-file")
def big_file():
def chunks():
with open("large.log", "rb") as f:
while chunk := f.read(8192):
yield chunk
return Response(chunks(), mimetype="application/octet-stream")Cookie в ответе
set_cookie записывает заголовок Set-Cookie; delete_cookie делает cookie истёкшим. Всегда задавайте httponly и samesite для безопасности. Cookie — часть ответа, а не тела запроса.
from flask import make_response
@app.route("/set-theme")
def set_theme():
resp = make_response("theme set")
resp.set_cookie("theme", "dark", max_age=30*86400, httponly=True, samesite="Lax")
return resp
@app.route("/clear-theme")
def clear_theme():
resp = make_response("cleared")
resp.delete_cookie("theme")
return respОбъект request (form/args/files)
Query-параметры (args)
request.args — MultiDict значений строки запроса. Используйте get со значением по умолчанию и преобразованием типа, а для повторяющихся ключей — getlist. Не обращайтесь по индексу: отсутствующий ключ даёт 400.
from flask import request
@app.route("/search")
def search():
q = request.args.get("q", "") # default ""
page = request.args.get("page", 1, type=int)
tags = request.args.getlist("tag") # /search?tag=a&tag=b -> ["a","b"]
return {"q": q, "page": page, "tags": tags}Данные формы
request.form содержит данные POST в application/x-www-form-urlencoded или multipart. Используйте .get(), чтобы избежать KeyError на необязательных полях. У GET-запросов форма пустая.
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
username = request.form.get("username")
password = request.form.get("password")
if not username or not password:
return "Missing fields", 400
return f"Welcome {username}"
return render_template("login.html")Загрузка файлов
request.files — MultiDict объектов FileStorage. Всегда пропускайте имена файлов от пользователя через secure_filename, чтобы убрать разделители путей и опасные символы перед сохранением.
from flask import request
from werkzeug.utils import secure_filename
import os
@app.route("/upload", methods=["POST"])
def upload():
file = request.files.get("file")
if not file or file.filename == "":
return "No file", 400
name = secure_filename(file.filename)
file.save(os.path.join("uploads", name))
return "saved"JSON-тело
get_json() разбирает тело как JSON только при Content-Type application/json. force=True игнорирует заголовок (осторожно). silent=True подавляет ошибки разбора.
from flask import request
@app.route("/api/echo", methods=["POST"])
def echo():
data = request.get_json() # returns None if not JSON
if data is None:
return "Expected JSON", 415
return {"you_sent": data}
# Force parsing even without the right header (risky)
@app.route("/api/force")
def force():
data = request.get_json(force=True)
return dataЗаголовки и cookie
request.headers — объект EnvironHeaders, похожий на словарь; request.cookies хранит входящие cookie от клиента. Оба доступны только для чтения: заголовки и cookie задавайте в ответе.
from flask import request
@app.route("/inspect")
def inspect():
auth = request.headers.get("Authorization")
accept = request.headers.get("Accept")
session_id = request.cookies.get("session_id")
return {
"auth": auth,
"accept": accept,
"session_id": session_id,
}Методы и свойства запроса
request даёт метаданные о соединении и теле. is_json проверяет Content-Type, is_secure — наличие HTTPS, а query_string — сырые байты после '?'.
from flask import request
@app.route("/state")
def state():
return {
"method": request.method,
"is_xhr": request.is_json,
"content_type": request.content_type,
"content_length": request.content_length,
"is_secure": request.is_secure,
"scheme": request.scheme,
"host": request.host,
"path": request.path,
"query_string": request.query_string.decode(),
}Шаблоны Jinja2
Рендеринг шаблонов
render_template загружает файл Jinja2 из папки templates/ и передаёт именованные аргументы как переменные. Синтаксис {{ }} выводит выражение; Flask автоматически экранирует HTML для безопасности.
from flask import render_template
@app.route("/<name>")
def hello(name):
return render_template("hello.html", name=name, title="Welcome")
# templates/hello.html
# <!DOCTYPE html>
# <html>
# <head><title>{{ title }}</title></head>
# <body>
# <h1>Hello {{ name }}!</h1>
# </body>
# </html>Переменные шаблона
Jinja2 поддерживает доступ по атрибуту (user.name) и по элементу (user['age']). Фильтр safe помечает строку как доверенную, чтобы её не экранировали, — применяйте только к содержимому, которое полностью контролируете.
# View
@app.route("/")
def index():
return render_template(
"index.html",
user={"name": "Alice", "age": 30},
items=["apple", "banana", "cherry"],
html_content="<b>safe?</b>",
)
# Template
# <p>Name: {{ user.name }}</p>
# <p>Age: {{ user["age"] }}</p>
# <p>First: {{ items[0] }}</p>
# <p>Raw HTML: {{ html_content | safe }}</p>Управляющие конструкции
Jinja2 поддерживает {% if %}, {% for %} и {% block %}. Внутри циклов специальная переменная loop даёт index, index0, first, last, length и revindex. Ветка for-else выполняется, когда итерируемое пусто.
{# if / elif / else #}
{% if user.age >= 18 %}
Adult
{% elif user.age >= 13 %}
Teen
{% else %}
Child
{% endif %}
{# for loop #}
<ul>
{% for item in items %}
<li>{{ loop.index }}: {{ item }}</li>
{% else %}
<li>No items</li>
{% endfor %}
</ul>Наследование шаблонов
extends подключает базовый шаблон, а дочерние переопределяют именованные блоки. Так общая вёрстка (навигация, скрипты) хранится в одном месте. super() выводит содержимое родительского блока.
{# templates/base.html #}
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Default{% endblock %}</title>
</head>
<body>
{% block content %}{% endblock %}
</body>
</html>
{# templates/child.html #}
{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h1>Welcome home</h1>
{% endblock %}Фильтры
Фильтры преобразуют значения через синтаксис конвейера (|) и при нимают аргументы. Регистрируйте свои фильтры в app.jinja_env.filters, чтобы переиспользовать логику в шаблонах.
{{ name | capitalize }} {# alice -> Alice #}
{{ price | round(2) }} {# 3.14159 -> 3.14 #}
{{ items | length }} {# count #}
{{ text | truncate(20) }} {# shorten #}
{{ tags | join(", ") }} {# ["a","b"] -> "a, b" #}
{{ value | default("n/a") }} {# fallback #}
{{ html | striptags }} {# remove HTML tags #}
{# Custom filter #}
def reverse_filter(s):
return s[::-1]
app.jinja_env.filters["reverse"] = reverse_filter
{{ "hello" | reverse }} {# olleh #}Макросы
Макросы — переиспользуемые фрагменты шаблона, как функции. Импортируйте их через {% from %} или {% import %}. Они избавляют от дублирования повторяющегося HTML (поля форм, карточки).
{# templates/macros.html #}
{% macro input(name, value="", type="text") %}
<input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}
{% macro label(text, for_id) %}
<label for="{{ for_id }}">{{ text }}</label>
{% endmacro %}
{# In another template #}
{% from "macros.html" import input, label %}
<form>
{{ label("Username", "u") }}
{{ input("username") }}
{{ label("Password", "p") }}
{{ input("password", type="password") }}
</form>Статические файлы
Отдача статических файлов
Flask автоматически регистрирует маршрут /static/<path:filename> для папки static. Всегда стройте URL через url_for, чтобы пути оставались корректными даже при изменении static_url_path.
# 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-аргументы для сброса кеша.
from flask import Flask, url_for
app = Flask(__name__)
with app.test_request_context():
print(url_for("static", filename="css/style.css"))
# /static/css/style.css
print(url_for("static", filename="js/app.js", _external=True))
# http://localhost/static/js/app.jsСвоя папка статических файлов
Переопределите static_folder (расположение на диске) и static_url_path (URL-префикс) под соглашения проекта. По умолчанию папка 'static' отображается на /static.
from flask import Flask
app = Flask(
__name__,
static_folder="assets", # folder on disk
static_url_path="/public", # URL prefix
)
# Now files in assets/ are served at /public/<filename>
# Template: url_for('static', filename='css/style.css') -> /public/css/style.cssFavicon
Браузеры по умолчанию запрашивают /favicon.ico в корне. Добавьте явный маршрут или подключите иконку через тег <link>. send_from_directory безопасно отдаёт файл из каталога.
from flask import send_from_directory
import os
@app.route("/favicon.ico")
def favicon():
return send_from_directory(
os.path.join(app.root_path, "static"),
"favicon.ico",
mimetype="image/vnd.microsoft.icon",
)
# Or place favicon.ico in static/ and link it:
# <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">Сброс кеша
Браузеры кешируют статические ресурсы по URL. Добавление хеша версии заставляет клиентов загрузить новые копии после изменения файла. В крупных проектах это автоматизирует сборщик (Vite, Flask-Assets).
# Append a version query param to force reloads
# <link href="{{ url_for('static', filename='css/app.css', v='1.2') }}">
# Or compute a hash at startup
import hashlib, os
def asset_version(filename):
path = os.path.join(app.static_folder, filename)
with open(path, "rb") as f:
return hashlib.md5(f.read()).hexdigest()[:8]
@app.template_filter("bust")
def bust(filename):
v = asset_version(filename)
return url_for("static", filename=filename) + f"?v={v}"
# Template: <link href="{{ 'css/app.css' | bust }}">Blueprint
Создание blueprint
Blueprint группирует связанные маршруты, шаблоны и статические файлы в модуль. Первый аргумент — имя blueprint; url_prefix добавляет префикс ко всем его маршрутам.
# auth.py
from flask import Blueprint, render_template
bp = Blueprint("auth", __name__, url_prefix="/auth")
@bp.route("/login")
def login():
return render_template("auth/login.html")
@bp.route("/register")
def register():
return render_template("auth/register.html")Регистрация blueprint
register_blueprint присоединяет blueprint к приложению. url_prefix можно переопределить при регистрации, поэтому один blueprint монтируется по разным путям в разных приложениях.
from flask import Flask
from auth import bp as auth_bp
from blog import bp as blog_bp
app = Flask(__name__)
app.register_blueprint(auth_bp) # /auth/*
app.register_blueprint(blog_bp, url_prefix="/blog") # /blog/*
# Register later, or with a name override
app.register_blueprint(auth_bp, name="alt_auth")Blueprint с префиксом URL
Задавайте url_prefix в Blueprint или при регистрации. Версионирование пути API (/api/v1) позволяет позже добавить /api/v2, не ломая существующих клиентов.
# api/__init__.py
from flask import Blueprint
bp = Blueprint("api", __name__, url_prefix="/api/v1")
@bp.route("/users")
def list_users():
return {"users": []}
@bp.route("/users/<int:uid>")
def get_user(uid):
return {"id": uid}
# All routes become /api/v1/users...Ресурсы blueprint
Blueprint может иметь свои шаблоны и статические папки. При поиске шаблонов сначала проверяется blueprint, затем приложение, поэтому локальные файлы blueprint перекрывают одноимённые общие.
bp = Blueprint(
"admin",
__name__,
url_prefix="/admin",
template_folder="templates", # blueprint-local templates
static_folder="static", # blueprint-local static
)
# Templates: blueprint lookups first, then app templates
# render_template("admin/dashboard.html")
# Static: url_for('admin.static', filename='css/admin.css')Обработчики ошибок blueprint
Обработчики ошибок уровня blueprint ловят только ошибки его маршрутов, давая разделу свои страницы ошибок. Обработчики уровня приложения берут всё непойманное.
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 объединяются, позволяя собирать большие приложения из малых модулей.
from flask import Blueprint
parent = Blueprint("parent", __name__, url_prefix="/parent")
child = Blueprint("child", __name__, url_prefix="/child")
@child.route("/info")
def info():
return "nested info"
parent.register_blueprint(child)
app.register_blueprint(parent)
# Final URL: /parent/child/infoКонтекст (g / session)
Контекст приложения
Контекст приложения делает current_app и g доступными вне запроса (например, в CLI-командах или фоновых задачах). Вне запроса его нужно активировать через app.app_context().
from flask import current_app, g
@app.route("/")
def index():
app_name = current_app.name
config_value = current_app.config["SECRET_KEY"]
return f"Running {app_name}"
# Push a context manually (scripts, shell)
with app.app_context():
print(current_app.config["DEBUG"])Объект g
g — пространство имён на время запроса для общих ресурсов вроде подключений к БД. Он сбрасывается на каждом запросе и очищается в обработчике teardown_appcontext.
from flask import g
import sqlite3
def get_db():
if "db" not in g:
g.db = sqlite3.connect("app.db")
g.db.row_factory = sqlite3.Row
return g.db
@app.teardown_appcontext
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()Контекст запроса
Контекст запроса привязывает request, session и url_for к потоку. Используйте test_request_context в тестах и скриптах, чтобы имитировать запрос без HTTP-сервера.
from flask import request
# Flask pushes a request context automatically during dispatch.
# Push one manually to use request/url_for outside a view:
with app.test_request_context("/?q=flask"):
print(request.args.get("q")) # flask
print(request.path) # /
# request_context for real WSGI environments
from werkzeug.test import EnvironBuilder
env = EnvironBuilder("/post/1").get_environ()
with app.request_context(env):
print(request.path)Прокси current_app и request
current_app, request, session и g — объекты LocalProxy, которые передают доступ к атрибутам активному контексту. Никогда не сохраняйте их в глобальную переменную — обращайтесь к ним во время вызова.
from flask import current_app, request, session, g
# These are LocalProxy objects, not the real thing.
# They resolve to the current context's object at access time.
@app.route("/")
def index():
current_app.logger.info("hit /")
g.request_start = time.time()
session["visited"] = True
return current_app.config["APP_NAME"]
# Avoid storing proxies in module-level variables;
# always access them inside a context.Объект session
session — подписанный словарь на основе cookie. Задайте app.secret_key, чтобы 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_* выполняются всегда, даже при ошибках, поэтому именно там закрывают подключения к БД и освобождают ресурсы.
# Per-request lifecycle:
# 1. Application context pushed
# 2. Request context pushed
# 3. before_request handlers run
# 4. View function runs
# 5. after_request handlers run (can modify response)
# 6. Request context popped
# 7. teardown_request handlers run
# 8. teardown_appcontext handlers run (close resources)
@app.before_request
def before():
g.start = time.time()
@app.teardown_request
def teardown(exc):
elapsed = time.time() - getattr(g, "start", time.time())
app.logger.debug("request took %.3fs", elapsed)Интеграция SQLAlchemy
Настройка Flask-SQLAlchemy
Flask-SQLAlchemy оборачивает SQLAlchemy и интегрирует её с контекстом приложения Flask. Задайте SQLALCHEMY_DATABASE_URI строкой подключения и отключите отслеживание изменений ради экономии памяти.
pip install flask-sqlalchemy
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
db = SQLAlchemy(app)
# In a factory, init with db.init_app(app)Определение моделей
Модели наследуются от db.Model; колонки — экземпляры db.Column. Частые типы: Integer, String, Text, DateTime, Boolean. Используйте unique=True и nullable=False для ограничений.
from datetime import datetime
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True, nullable=False)
email = db.Column(db.String(120), unique=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
def __repr__(self):
return f"<User {self.username}>"
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200), nullable=False)
body = db.Column(db.Text)
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))Выборка данных
Model.query — удобный интерфейс запросов. filter_by(keyword=value) прост; filter(expression) поддерживает операторы вроде >, <, like, in_. paginate() возвращает элементы и метаданные страницы.
# Fetch all
users = User.query.all()
# Primary key lookup
user = User.query.get(1)
# Filter
admins = User.query.filter_by(role="admin").all()
active = User.query.filter(User.email.isnot(None)).first()
# Order, limit, paginate
recent = User.query.order_by(User.created_at.desc()).limit(10).all()
page = User.query.paginate(page=2, per_page=20)
# Count
total = User.query.count()Добавление и обновление
Все изменения идут в транзакции через db.session. add добавляет новый объект; commit записывает. При ошибке откатите через db.session.rollback(), чтобы сессия осталась рабочей.
# Create
u = User(username="alice", email="[email protected]")
db.session.add(u)
db.session.commit()
# Update
u.email = "[email protected]"
db.session.commit()
# Delete
db.session.delete(u)
db.session.commit()
# Bulk insert
db.session.add_all([User(username="b"), User(username="c")])
db.session.commit()Связи
db.relationship описывает связь между моделями. backref добавляет обратный атрибут. lazy='dynamic' возвращает объект запроса вместо списка — удобно для больших коллекций, которые нужно дополнительно фильтровать.
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80))
posts = db.relationship("Post", backref="author", lazy="dynamic")
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200))
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))
# Usage
user = User.query.get(1)
user.posts.all() # list of posts
post = Post.query.get(5)
post.author.username # backref to userМиграции с Flask-Migrate
Flask-Migrate оборачивает Alembic для версионирования схемы. Запустите migrate, чтобы сгенерировать скрипт по изменениям моделей, затем upgrade, чтобы применить его. Всегда просматривайте автогенерированные скрипты перед коммитом.
pip install flask-migrate
from flask_migrate import Migrate
migrate = Migrate(app, db)
# CLI commands
# flask db init # create migrations folder
# flask db migrate -m "create users"
# flask db upgrade # apply migrations
# flask db downgrade # revert one step
# flask db current # show current revisionWTForms (Flask-WTF)
Установка Flask-WTF
Flask-WTF интегрирует WTForms с Flask и автоматически добавляет защиту CSRF. Нужен SECRET_KEY, чтобы подписать CSRF-токен. Отключайте CSRF только для публичных API-endpoint.
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 и другое.
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-поле.
{# 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. При ошибке перерендерите шаблон, чтобы показать ошибки.
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 часто используют для подтверждения пароля. Объединяйте их в список: они выполняются по порядку до первой ошибки.
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.
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed
class UploadForm(FlaskForm):
image = FileField("Image", validators=[
FileRequired(),
FileAllowed(["jpg", "png", "gif"], "Images only!"),
])
submit = SubmitField("Upload")
@app.route("/upload", methods=["GET", "POST"])
def upload():
form = UploadForm()
if form.validate_on_submit():
f = form.image.data
f.save("uploads/" + f.filename)
return "uploaded"
return render_template("upload.html", form=form)Аутентификация Flask-Login
Настройка Flask-Login
Flask-Login управляет сессиями пользователей: вход, выход и запоминание. Задайте login_view, куда перенаправляются неаутентифицированные пользователи. login_message показывается при этом редиректе.
pip install flask-login
from flask import Flask
from flask_login import LoginManager
app = Flask(__name__)
app.config["SECRET_KEY"] = "secret"
login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = "login"
login_manager.login_message = "Please log in to access this page."Модель пользователя
Модель пользователя должна подмешивать UserMixin (даёт is_authenticated, is_active, get_id и др.) и реализовывать колбэк user_loader, возвращающий пользователя по ID. Никогда не храните пароли в открытом виде — хешируйте их.
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. Всегда проверяйте пароль по хешу перед входом и показывайте общее сообщение об ошибке при неудаче.
from flask import render_template, redirect, url_for, flash
from flask_login import login_user
from forms import LoginForm
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit():
user = User.query.filter_by(username=form.username.data).first()
if user and user.check_password(form.password.data):
login_user(user, remember=form.remember.data)
return redirect(url_for("dashboard"))
flash("Invalid username or password")
return render_template("login.html", form=form)Защита маршрутов
Декоратор @login_required отклоняет анонимных пользователей и перенаправляет их на login_view. current_user — прокси вошедшего пользователя (или AnonymousUserMixin), доступный в обработчиках и шаблонах.
from flask_login import login_required, current_user
@app.route("/dashboard")
@login_required
def dashboard():
return f"Welcome {current_user.username}"
@app.route("/settings")
@login_required
def settings():
return render_template("settings.html", user=current_user)
# Unauthenticated users redirect to login_view
# @login_required must be the innermost decoratorВыход
logout_user убирает пользователя из сессии. Защитите маршрут через @login_required, чтобы выходить могли только вошедшие. После выхода перенаправьте на публичную страницу (главную или вход).
from flask_login import logout_user, login_required
from flask import redirect, url_for, flash
@app.route("/logout")
@login_required
def logout():
logout_user()
flash("You have been logged out.")
return redirect(url_for("index"))
# logout_user() clears the session and cookiesRemember me и current_user
remember=True ставит отдельный cookie, чтобы пользователь оставался в системе после закрытия браузера. current_user работает и в обработчиках, и в шаблонах, позволяя условно рендерить интерфейс по статусу аутентификации.
from flask_login import current_user
# In the login view
login_user(user, remember=True)
# remember=True stores a separate long-lived cookie
# so the session survives a browser restart.
# current_user is available everywhere a context exists
@app.route("/")
def index():
if current_user.is_authenticated:
return f"Hi {current_user.username}"
return "Welcome, guest"
# In templates:
# {% if current_user.is_authenticated %}
# <a href="{{ url_for('logout') }}">Logout</a>
# {% endif %}Обработка ошибок
abort()
abort() немедленно прерывает обработчик и возвращает HTTP-ошибку. Передайте код состояния и необязательное сообщение. Он бросает HTTPException, который 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(), и исключения, соответствующие этому коду.
from flask import render_template
@app.errorhandler(404)
def not_found(e):
return render_template("errors/404.html"), 404
@app.errorhandler(403)
def forbidden(e):
return render_template("errors/403.html"), 403
@app.errorhandler(500)
def server_error(e):
return render_template("errors/500.html"), 500Обработчики для исключений
Можно регистрировать обработчики для своих классов исключений, а не только для HTTP-кодов. Бросок исключения в любом месте обработчика вызывает обработчик, централизуя ответы на ошибки предметной области.
from werkzeug.exceptions import HTTPException
class InvalidUsage(Exception):
status_code = 400
def __init__(self, message, status_code=None, payload=None):
super().__init__()
self.message = message
if status_code is not None:
self.status_code = status_code
self.payload = payload
@app.errorhandler(InvalidUsage)
def handle_invalid_usage(e):
return {"error": e.message}, e.status_code
@app.route("/raise")
def raise_err():
raise InvalidUsage("Bad input", status_code=422)Общий обработчик 404
Общий обработчик Exception — крайняя мера для 500. Повторно бросайте HTTPException, чтобы встроенные страницы продолжали работать, и логируйте трассировку. Не допускайте утечки трассировок пользователям в production.
@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 направляйте логи в централизованный сервис.
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) имеет приоритет для этого кода.