Быстрый старт

Минимальное приложение

Минимальное приложение Flask выглядит примерно так:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello_world():
    return "<p>Hello, World!</p>"

Что делает этот код?

1. Сначала мы импортировали класс Flask. Экземпляр этого класса будет нашим приложением WSGI.
2. Далее мы создаём экземпляр этого класса. Первым аргументом является имя модуля или пакета приложения. __name__ — удобное сокращение, подходящее для большинства случаев. Это необходимо, чтобы Flask знал, где искать ресурсы, такие как шаблоны и статические файлы.
3. Затем мы используем декоратор route(), чтобы указать Flask, какой URL должен активировать нашу функцию.
4. Функция возвращает сообщение, которое мы хотим отобразить в браузере пользователя. По умолчанию тип содержимого — HTML, поэтому HTML в строке будет рендериться браузером.

Сохраните его как hello.py или что-то подобное. Убедитесь, что вы не назвали своё приложение flask.py, так как это вызовет конфликт с самим Flask.

Для запуска приложения используйте команду flask или python -m flask. Вам нужно указать Flask, где находится ваше приложение, с помощью опции --app.

$ flask --app hello run
 * Serving Flask app 'hello'
 * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)

Это запускает очень простой встроенный сервер, который достаточно хорош для тестирования, но, вероятно, не то, что вам нужно для производства. Для вариантов развертывания см. Развертывание в производство.

Теперь перейдите по адресу http://127.0.0.1:5000/, и вы должны увидеть приветствие «hello world».

Если другой процесс уже использует порт 5000, вы увидите OSError: [Errno 98] или OSError: [WinError 10013], когда сервер пытается запуститься. Подробнее о том, как справиться с этим, см. Адрес уже используется.

$ flask run --host=0.0.0.0

Режим отладки

Команда flask run может делать больше, чем просто запускать сервер разработки. Включив режим отладки, сервер будет автоматически перезагружаться при изменении кода и покажет интерактивный отладчик в браузере, если во время запроса произойдёт ошибка.

Чтобы включить режим отладки, используйте опцию --debug.

$ flask --app hello run --debug
 * Serving Flask app 'hello'
 * Debug mode: on
 * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: nnn-nnn-nnn

См. также:

• Сервер разработки и Интерфейс командной строки для получения информации о запуске в режиме отладки.
• Отладка ошибок приложения для получения информации об использовании встроенного отладчика и других отладчиков.
• Ведение журнала и Обработка ошибок приложения для ведения журнала ошибок и отображения красивых страниц ошибок.

Экранирование HTML

При возвращении HTML (по умолчанию тип ответа в Flask), любые пользовательские значения, отображаемые в выводе, должны быть экранированы для защиты от атак с помощью инъекций. Шаблоны HTML, рендеренные с помощью Jinja, представленные позже, будут делать это автоматически.

escape(), показанный здесь, может использоваться вручную. Он опущен во многих примерах для краткости, но вы всегда должны знать, как используете недоверенные данные.

from markupsafe import escape

@app.route("/<name>")
def hello(name):
    return f"Hello, {escape(name)}!"

Если пользователь смог отправить имя <script>alert("bad")</script>, экранирование заставит его отобразиться как текст, а не выполнит сценарий в браузере пользователя.

<name> в маршруте захватывает значение из URL и передаёт его функции представления. Эти правила переменных описаны ниже.

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

Современные веб-приложения используют осмысленные URL-адреса, чтобы помочь пользователям. Пользователи с большей вероятностью оценят страницу и вернутся на неё, если на странице используется осмысленный URL-адрес, который они могут запомнить и использовать для прямого перехода на страницу.

Используйте декоратор route() для привязки функции к URL.

@app.route('/')
def index():
    return 'Index Page'

@app.route('/hello')
def hello():
    return 'Hello, World'

Вы можете сделать больше! Вы можете сделать части URL динамичными и прикрепить несколько правил к одной функции.

from markupsafe import escape

@app.route('/user/<username>')
def show_user_profile(username):
    # show the user profile for that user
    return f'User {escape(username)}'

@app.route('/post/<int:post_id>')
def show_post(post_id):
    # show the post with the given id, the id is an integer
    return f'Post {post_id}'

@app.route('/path/<path:subpath>')
def show_subpath(subpath):
    # show the subpath after /path/
    return f'Subpath {escape(subpath)}'

@app.route('/projects/')
def projects():
    return 'The project page'

@app.route('/about')
def about():
    return 'The about page'

from flask import url_for

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

@app.route('/login')
def login():
    return 'login'

@app.route('/user/<username>')
def profile(username):
    return f'{username}\'s profile'

with app.test_request_context():
    print(url_for('index'))
    print(url_for('login'))
    print(url_for('login', next='/'))
    print(url_for('profile', username='John Doe'))

/
/login
/login?next=/
/user/John%20Doe

from flask import request

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        return do_the_login()
    else:
        return show_the_login_form()

@app.get('/login')
def login_get():
    return show_the_login_form()

@app.post('/login')
def login_post():
    return do_the_login()

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

Динамические веб-приложения также нуждаются в статических файлах. Обычно оттуда берутся файлы CSS и JavaScript. В идеале ваш веб-сервер настроен на их предоставление, но во время разработки Flask может это сделать и сам. Просто создайте папку с именем static в своем пакете или рядом с модулем, и она будет доступна по адресу /static в приложении.

Для генерации URL-адресов статических файлов используйте специальное имя конечной точки 'static':

url_for('static', filename='style.css')

Файл должен храниться в файловой системе как static/style.css.

Отображение шаблонов

Генерация HTML изнутри Python не является приятной задачей и довольно громоздка, потому что вам нужно самостоятельно обрабатывать HTML-экранирование, чтобы обеспечить безопасность приложения. По этой причине Flask автоматически настраивает для вас движок шаблонов Jinja2.

Шаблоны могут использоваться для генерации любого типа текстовых файлов. Для веб-приложений вы в основном будете генерировать HTML-страницы, но также можете генерировать Markdown, простой текст для писем и многое другое.

Для справки по HTML, CSS и другим веб-API используйте MDN Web Docs.

Для отображения шаблона можно использовать метод render_template(). Всё, что вам нужно сделать, это указать имя шаблона и переменные, которые вы хотите передать движку шаблонов в качестве именованных аргументов. Вот простой пример отображения шаблона:

from flask import render_template

@app.route('/hello/')
@app.route('/hello/<name>')
def hello(name=None):
    return render_template('hello.html', person=name)

Flask будет искать шаблоны в папке templates. Таким образом, если ваше приложение является модулем, эта папка находится рядом с ним, если это пакет, она находится внутри вашего пакета:

Случай 1: модуль:

/application.py
/templates
    /hello.html

Случай 2: пакет:

/application
    /__init__.py
    /templates
        /hello.html

Для шаблонов вы можете использовать весь потенциал Jinja2. Подробнее ознакомьтесь с официальной документацией по шаблонам Jinja2.

Вот пример шаблона:

<!doctype html>
<title>Hello from Flask</title>
{% if person %}
  <h1>Hello {{ person }}!</h1>
{% else %}
  <h1>Hello, World!</h1>
{% endif %}

Внутри шаблонов также есть доступ к объектам config, request, session и g [1], а также к функциям url_for() и get_flashed_messages().

Шаблоны особенно полезны при использовании наследования. Если вы хотите узнать, как это работает, обратитесь к Наследованию шаблонов. В основном наследование шаблонов позволяет сохранять определенные элементы на каждой странице (такие как заголовок, навигация и подвал).

Автоматическое экранирование включено, поэтому если person содержит HTML, он будет автоматически экранирован. Если вы можете доверять переменной и знаете, что она будет безопасным HTML (например, потому что она пришла из модуля, который преобразует разметку вики в HTML), вы можете отметить её как безопасную, используя класс Markup или фильтр |safe в шаблоне. Для получения дополнительных примеров обратитесь к документации Jinja 2.

Вот базовое введение в работу с классом Markup:

>>> from markupsafe import Markup
>>> Markup('<strong>Hello %s!</strong>') % '<blink>hacker</blink>'
Markup('<strong>Hello &lt;blink&gt;hacker&lt;/blink&gt;!</strong>')
>>> Markup.escape('<blink>hacker</blink>')
Markup('&lt;blink&gt;hacker&lt;/blink&gt;')
>>> Markup('<em>Marked up</em> &raquo; HTML').striptags()
'Marked up » HTML'

Получение данных запроса

Для веб-приложений крайне важно реагировать на данные, которые клиент отправляет серверу. В Flask эта информация предоставляется глобальным объектом request. Если у вас есть опыт работы с Python, вы, возможно, задаетесь вопросом, как этот объект может быть глобальным и как Flask при этом сохраняет потокобезопасность. Ответ — контекстные локальные переменные:

from flask import request

with app.test_request_context('/hello', method='POST'):
    # now you can do something with the request until the
    # end of the with block, such as basic assertions:
    assert request.path == '/hello'
    assert request.method == 'POST'

with app.request_context(environ):
    assert request.method == 'POST'

from flask import request

@app.route('/login', methods=['POST', 'GET'])
def login():
    error = None
    if request.method == 'POST':
        if valid_login(request.form['username'],
                       request.form['password']):
            return log_the_user_in(request.form['username'])
        else:
            error = 'Invalid username/password'
    # the code below is executed if the request method
    # was GET or the credentials were invalid
    return render_template('login.html', error=error)

searchword = request.args.get('key', '')

from flask import request

@app.route('/upload', methods=['GET', 'POST'])
def upload_file():
    if request.method == 'POST':
        f = request.files['the_file']
        f.save('/var/www/uploads/uploaded_file.txt')
    ...

from werkzeug.utils import secure_filename

@app.route('/upload', methods=['GET', 'POST'])
def upload_file():
    if request.method == 'POST':
        file = request.files['the_file']
        file.save(f"/var/www/uploads/{secure_filename(file.filename)}")
    ...

from flask import request

@app.route('/')
def index():
    username = request.cookies.get('username')
    # use cookies.get(key) instead of cookies[key] to not get a
    # KeyError if the cookie is missing.

from flask import make_response

@app.route('/')
def index():
    resp = make_response(render_template(...))
    resp.set_cookie('username', 'the username')
    return resp

Перенаправления и ошибки

Чтобы перенаправить пользователя на другой конечный пункт, используйте функцию redirect(); чтобы прервать запрос с ошибкой, используйте функцию abort():

from flask import abort, redirect, url_for

@app.route('/')
def index():
    return redirect(url_for('login'))

@app.route('/login')
def login():
    abort(401)
    this_is_never_executed()

Это довольно бесполезный пример, потому что пользователь будет перенаправлен с главной страницы на страницу, к которой он не имеет доступа (401 означает отказ в доступе), но он показывает, как это работает.

По умолчанию для каждой ошибки отображается простая страница ошибки. Если вы хотите настроить страницу ошибки, вы можете использовать декоратор errorhandler():

from flask import render_template

@app.errorhandler(404)
def page_not_found(error):
    return render_template('page_not_found.html'), 404

Обратите внимание на 404 после вызова render_template(). Это сообщает Flask, что код состояния этой страницы должен быть 404, что означает «не найдено». По умолчанию предполагается 200, что означает: «Всё прошло хорошо».

Для получения более подробной информации см. Обработка ошибок приложения.

О ответах

Значение, возвращаемое функцией представления, автоматически преобразуется в объект ответа для вас. Если возвращаемое значение — строка, оно преобразуется в объект ответа со строкой в качестве тела ответа, кодом состояния 200 OK и MIME-типом text/html. Если возвращаемое значение — словарь или список, вызывается jsonify(), чтобы создать ответ. Логика, которую Flask применяет для преобразования возвращаемых значений в объекты ответа, следующая:

1. Если возвращается объект ответа правильного типа, он возвращается непосредственно из представления.
2. Если это строка, создается объект ответа с этими данными и значениями по умолчанию.
3. Если это итератор или генератор, возвращающий строки или байты, он обрабатывается как потоковый ответ.
4. Если это словарь или список, объект ответа создается с помощью jsonify().
5. Если возвращается кортеж, элементы кортежа могут предоставить дополнительную информацию. Такие кортежи должны быть в формате (response, status), (response, headers), или (response, status, headers). Значение status переопределит код состояния, а headers может быть списком или словарем дополнительных значений заголовков.
6. Если ничего из вышеперечисленного не работает, Flask предположит, что возвращаемое значение является допустимым приложением WSGI, и преобразует его в объект ответа.

Если вы хотите получить доступ к объекту результирующего ответа внутри представления, вы можете использовать функцию make_response().

Представьте, что у вас есть представление такого вида:

from flask import render_template

@app.errorhandler(404)
def not_found(error):
    return render_template('error.html'), 404

Вам просто нужно обернуть выражение возврата с помощью make_response() и получить объект ответа, чтобы изменить его, а затем вернуть его:

from flask import make_response

@app.errorhandler(404)
def not_found(error):
    resp = make_response(render_template('error.html'), 404)
    resp.headers['X-Something'] = 'A value'
    return resp

@app.route("/me")
def me_api():
    user = get_current_user()
    return {
        "username": user.username,
        "theme": user.theme,
        "image": url_for("user_image", filename=user.image),
    }

@app.route("/users")
def users_api():
    users = get_all_users()
    return [user.to_json() for user in users]

Сессии

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

Для использования сессий необходимо установить секретный ключ. Вот как работают сессии:

from flask import session

# Set the secret key to some random bytes. Keep this really secret!
app.secret_key = b'_5#y2L"F4Q8z\n\xec]/'

@app.route('/')
def index():
    if 'username' in session:
        return f'Logged in as {session["username"]}'
    return 'You are not logged in'

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        session['username'] = request.form['username']
        return redirect(url_for('index'))
    return '''
        <form method="post">
            <p><input type=text name=username>
            <p><input type=submit value=Login>
        </form>
    '''

@app.route('/logout')
def logout():
    # remove the username from the session if it's there
    session.pop('username', None)
    return redirect(url_for('index'))

$ python -c 'import secrets; print(secrets.token_hex())'
'192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf'

Примечание о сессиях на основе куки: Flask преобразует значения, которые вы помещаете в объект сессии, в сериализованные куки. Если вы обнаруживаете, что некоторые значения не сохраняются между запросами, куки действительно включены, и вы не получаете ясного сообщения об ошибке, проверьте размер куки в ответах вашей страницы по сравнению с размером, поддерживаемым веб-браузерами.

Помимо стандартных сессий на стороне клиента, если вы хотите обрабатывать сессии на стороне сервера, существуют несколько расширений Flask, которые поддерживают это.

Сообщения всплывающие

Хорошие приложения и пользовательские интерфейсы ориентированы на обратную связь. Если пользователь не получает достаточной обратной связи, он, скорее всего, возненавидит приложение. Flask предоставляет очень простой способ предоставления обратной связи пользователю с помощью системы всплывающих сообщений. Система всплывающих сообщений, по сути, позволяет записывать сообщение в конце запроса и получать доступ к нему в следующем (и только в следующем) запросе. Обычно это сочетается с шаблоном макета для отображения сообщения.

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

Ведение журнала

Иногда вы можете столкнуться со ситуацией, когда данные должны быть корректными, но на самом деле таковыми не являются. Например, у вас может быть некоторый клиентский код, который отправляет HTTP-запрос на сервер, но он явно имеет неправильный формат. Это может быть вызвано вмешательством пользователя в данные или сбоем клиентского кода. В большинстве случаев достаточно ответить 400 Bad Request в этой ситуации, но иногда этого недостаточно, и код должен продолжать работать.

Вы по-прежнему можете записать в журнал, что произошло что-то подозрительное. Именно здесь пригодятся логгеры. Начиная с Flask 0.3, для вас предварительно настроен логгер.

Вот несколько примеров вызовов логгера:

app.logger.debug('A value for debugging')
app.logger.warning('A warning occurred (%d apples)', 42)
app.logger.error('An error occurred')

Присоединенный logger — стандартный логгер Logger, поэтому обратитесь к официальной документации logging для получения дополнительной информации.

См. Обработка ошибок приложения.

Включение WSGI-среднего программного обеспечения

Для добавления WSGI-среднего программного обеспечения к вашему приложению Flask оберните атрибут wsgi_app приложения. Например, для применения среднего программного обеспечения Werkzeug ProxyFix для работы за Nginx:

from werkzeug.middleware.proxy_fix import ProxyFix
app.wsgi_app = ProxyFix(app.wsgi_app)

Обертывание app.wsgi_app вместо app означает, что app по-прежнему указывает на ваше приложение Flask, а не на среднее программное обеспечение, поэтому вы можете продолжать использовать и настраивать app напрямую.

Использование расширений Flask

Расширения — это пакеты, которые помогают выполнять распространённые задачи. Например, Flask-SQLAlchemy предоставляет поддержку SQLAlchemy, что упрощает и облегчает использование с Flask.

Дополнительную информацию об расширениях Flask см. в разделе Расширения.

Развёртывание на веб-сервере

Готовы развернуть ваше новое приложение Flask? См. Развёртывание в продакшен.