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

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

Минимальное приложение 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-страницы, но вы также можете генерировать уценку, простой текст для электронных писем и любые другие файлы.

Для ссылки на HTML, CSS и другие веб-интерфейсы используйте 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', name=name)

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

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

/application.py
/templates
    /hello.html

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

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

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

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

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

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

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

Автоматическое экранирование включено, поэтому если name содержит 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 и миметипом text/html. Если возвращаемое значение представляет собой dict или список, для создания ответа вызывается jsonify(). Логика, которую применяет Flask для преобразования возвращаемых значений в объекты ответа, выглядит следующим образом:

1. Если возвращается объект ответа правильного типа, он возвращается непосредственно из представления.

2. Если это строка, то создается объект ответа с этими данными и параметрами по умолчанию.

3. Если это итератор или генератор, возвращающий строки или байты, то он рассматривается как потоковый ответ.

4. Если это dict или список, то объект ответа создается с помощью 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

Вам просто нужно обернуть выражение return выражением 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, который позволяет хранить информацию, специфичную для пользователя, от одного запроса к другому. Это реализовано поверх cookies и подписывает cookies криптографически. Это означает, что пользователь может посмотреть содержимое вашего cookie, но не сможет его изменить, если только не знает секретный ключ, используемый для подписи.

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

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

Помимо стандартных сессий на стороне клиента, если вы хотите обрабатывать сессии на стороне сервера, есть несколько расширений 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? Смотрите Развертывание в производство.