Сообщить об ошибке.

Описание параметров конфигурации приложения на Flask

Веб-приложениям Flask нужна какая-то настройка. Существуют различные параметры конфигурации, которые можно изменить в зависимости от режима работы, например, переключение режима отладки debug, установка секретного ключа и другие подобные вещи, зависящие от среды выполнения.

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

Независимо от того, каким образом загружается конфигурация, во Flask всегда доступен объект конфигурации, который содержит загруженные значения конфигурации: это атрибут объекта приложения app.config. Это то место, куда сам Flask помещает определенные значения конфигурации, а также куда расширения могут помещать свои значения конфигурации. Здесь, также, можно хранить какие-то свои значения конфигурации.

Содержание:

Изменение параметров конфигурации Flask.

Значение экземпляра приложения app.config является подклассом словаря Python и может быть изменен так же, как любой словарь:

app = Flask(__name__)
app.config['TESTING'] = True

Некоторые значения конфигурации также передаются в объект приложения Flask, чтобы их можно было читать и записывать прям оттуда:

app.testing = True

Чтобы обновить сразу несколько ключей/параметров конфигурации, можно использовать метод dict.update():

app.config.update(
    TESTING=True,
    SECRET_KEY='a1dcbe59291f58c089fbab4feaf8ee8e2f44f05cdd4465e0d9c726938b2eeaab'
)

Управление режимом работы Flask и функцией отладки.

Внимание. Переменная среды FLASK_ENV и атрибут app.env устарели с версии Flask 2.2.0 и удален с версии 2.3.0, что устраняет различие между режимами разработки и отладки. Режим отладки следует контролировать напрямую с помощью параметра CLI --debug или app.run(debug=True).

Например:

$ export FLASK_APP=yourapplication
$ flask run --debug

Значение конфигурации DEBUG является особенным, поскольку оно может вести себя непоследовательно, если его изменить после начала настройки приложения. Чтобы надежно установить режим отладки, используйте параметр --debug в команде запуска flask или flask. flask run по умолчанию будет использовать интерактивный отладчик и перезагрузку в режиме отладки.

Значение конфигурации DEBUG являются особенным, т. к. они могут вести себя непоследовательно, если его изменить после начала настройки приложения. Чтобы надежно установить режим отладки, используйте параметр --debug в команде запуска flask. Команда flask run по умолчанию будет использовать интерактивный отладчик и перезагрузку в режиме отладки.

Среда указывает Flask, его расширениям и другим программам, таким как Sentry, в каком контексте работает Flask. Он управляется переменной среды окружения FLASK_ENV (удалено с версии Flask 2.3.0) и по умолчанию установлена на 'production'.

Установка FLASK_ENV='development' (удалено с версии Flask 2.3.0), автоматически включит режим отладки DEBUG. Экземпляр приложения Flask - app.run() по умолчанию будет использовать интерактивный отладчик и перезагрузку кода при его изменении. Чтобы управлять этим отдельно от режима работы, используйте флаг среды окружения FLASK_DEBUG.

Чтобы переключить Flask в среду разработки и включить режим отладки, установите FLASK_ENV (удалено с версии Flask 2.3.0):

# удалено с версии Flask 2.3.0
$ export FLASK_ENV=development
$ flask run

# во Flask 2.2.0 нужно добавить `app.run(debug=True)`
$ export FLASK_APP=yourapplication
$ flask run

# или добавить при запуске параметр CLI `--debug`
# оставив в коде `app.run()` 
$ export FLASK_APP=yourapplication
$ flask run --debug

Рекомендуется использовать режим разработки, как описано выше. В конфигурации или коде можно установить DEBUG, но это настоятельно не рекомендуется. Эти параметры, заданные в app.config не могут быть заранее прочитаны командой $flask run на стадии запуска приложения, а некоторые расширения могут уже настроиться на основе предыдущего значения.

При использовании режима отладки загрузчик будет срабатывать всякий раз, когда изменяется код Python или импортированные модули. Загрузчик может просматривать дополнительные файлы с опцией --extra-files. Несколько путей разделяются : или ; в Windows.

$ flask run --extra-files file1:dirA/file2:dirB/
 * Running on http://127.0.0.1:8000/
 * Detected change in '/path/to/file1', reloading

Загрузчик также может игнорировать файлы, использующие шаблоны как в модуле fnmatch с параметром --exclude-patterns. Несколько шаблонов разделяются : или ; в Windows.

Список параметров конфигурации, используемые во Flask.

ENV:

Параметр ENV определяет, в каком режиме/среде выполняется приложение. Flask и расширения имеют разное поведение в зависимости от режима работы, например в режиме разработки ('development'), автоматически включается режим отладки.

Этому ключу конфигурации, соответствует атрибут экземпляра приложения app.env (устарело с версии Flask 2.2.0). Он устанавливается переменной среды окружения FLASK_ENV (удалено с версии Flask 2.3.0) и может вести себя не так, как ожидалось, если он установлен в коде.

Внимание! Не включайте режим разработки на боевом сервере.

Внимание. Переменная среды FLASK_ENV и атрибут app.env устарели с версии Flask 2.2.0 и удалены с версии Flask 2.3.0, что устраняет различие между режимами разработки и отладки. Режим отладки следует контролировать напрямую с помощью параметра CLI --debug или app.run(debug=True).

DEBUG:

Параметр DEBUG включает режим отладки. При использовании команды $flask run для запуска сервера разработки, будет отображаться интерактивный отладчик для необработанных исключений, а сервер будет перезагружаться при каждом изменении кода.

Этому ключу конфигурации соответствует атрибут экземпляра приложения app.debug. Режим отладки включается автоматически, когда ENV='development', и переопределяется переменной среды окружения FLASK_DEBUG. Если параметр задан в коде, то он может вести себя не так, как ожидалось.

Внимание! Не включайте режим разработки на боевом сервере.

По умолчанию: True, если ENV='development', или False в противном случае.

TESTING:

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

По умолчанию: False.

PROPAGATE_EXCEPTIONS:

Если установлен параметр PROPAGATE_EXCEPTIONS, то исключения возникают повторно, а не обрабатываются обработчиками ошибок веб-приложения. Если НЕ установлен, то включится автоматически, если включены параметры TESTING или DEBUG.

По умолчанию: None

PRESERVE_CONTEXT_ON_EXCEPTION:

Если установлен параметр PRESERVE_CONTEXT_ON_EXCEPTION, то не будет выдаваться контекст запроса при возникновении исключения. Если НЕ установлен, то включится автоматически, при включении параметра DEBUG. Это позволяет отладчикам анализировать данные запроса на предмет ошибок и, как правило, не требует настройки напрямую.

По умолчанию: None

TRAP_HTTP_EXCEPTIONS:

Если TRAP_HTTP_EXCEPTIONS установлен в True и нет обработчика для исключения типа HTTPException, то вызывает его повторно, чтобы он обрабатывался интерактивным отладчиком, вместо того, чтобы возвращать его как простой ответ об HTTP-ошибке (например 500).

По умолчанию: False

TRAP_BAD_REQUEST_ERRORS:

Если установлен параметр TRAP_BAD_REQUEST_ERRORS, то при попытках получить из объекта запроса доступ к ключу, которого не существует, таких как request.args и request.form, будет вызывать ошибку как необработанное исключение, и не будет возвращать страницу с ошибкой 400 Bad Request. Это более конкретная версия параметра TRAP_HTTP_EXCEPTIONS.

Если НЕ установлен, то включается автоматически в режиме отладки.

По умолчанию: None

SECRET_KEY:

Параметр SECRET_KEY устанавливает секретный ключ, который будет использоваться для безопасной подписи файла cookie, используемого в сессии/сеансе и может использоваться для любых других потребностей, связанных с безопасностью, расширениями или веб-приложением. Это должен быть длинная случайная байтовая или текстовая строка. Например:

$ python3 -c 'import os; print(os.urandom(16))'
b'_5#y2L"F4Q8z\n\xec]/'

или

python3 -c 'import secrets; print(secrets.token_hex())'
a1dcbe59291f58c089fbab4feaf8ee8e2f44f05cdd4465e0d9c726938b2eeaab

По умолчанию: None

Внимание! Не раскрывайте секретный ключ при публикации кода приложения.

Важно! Помните, что файлы cookie сессии/сеанса Flask подписаны секретным ключом (защищены от подделки), НО НЕ ЗАШИФРОВАНЫ, по этому данные сессии/сеанса можно локально декодировать. Следовательно НИКОГДА не записывайте в сессионные файлы cookie пароли и другую критически важную информацию из базы данных.

Дополнительно смотрите материал "Безопасность веб-приложения на Flask"

SESSION_COOKIE_NAME:

Параметр SESSION_COOKIE_NAME отвечает за имя файла cookie сессии/сеанса. Его можно изменить, если уже есть файл cookie с таким именем.

По умолчанию: 'session'

SESSION_COOKIE_DOMAIN:

Параметр SESSION_COOKIE_DOMAIN - это правило сопоставления домена, для которого будет действителен cookie сессии/сеанса. Если не установлен, то cookie будет действителен для всех субдоменов, основного домена SERVER_NAME. Если False, то домен cookie не будет установлен.

По умолчанию: None.

С версии Flask 2.3.0 SESSION_COOKIE_DOMAIN не возвращается к SERVER_NAME. По умолчанию домен не устанавливается, что современные браузеры интерпретируют как точное совпадение, а не как совпадение поддомена. Предупреждения о локальном хосте и IP-адресах также удалены.

SESSION_COOKIE_PATH:

Параметр SESSION_COOKIE_PATH - это путь, для которого будет действителен cookie сессии/сеанса. Если не установлен, то cookie будет действителен под APPLICATION_ROOT или '/'.

По умолчанию: None.

SESSION_COOKIE_HTTPONLY:

Если параметр SESSION_COOKIE_HTTPONLY установлен в True, то браузеры не разрешают JavaScript доступ к файлам cookie, помеченным как "HTTP only" в целях безопасности.

По умолчанию: True.

SESSION_COOKIE_SECURE:

Если параметр SESSION_COOKIE_SECURE установлен в True, то браузеры будут отправлять файлы cookie с запросами через HTTPS, только если файл cookie помечен как "secure". Этот параметр имеет смысл, только если приложение работает по протоколу HTTPS.

По умолчанию: False

SESSION_COOKIE_SAMESITE:

Параметр SESSION_COOKIE_SAMESITE ограничивает способ отправки файлов cookie с запросами с внешних сайтов. Может быть установлен на Lax (рекомендуется) или Strict. Дополнительно смотрите материал "Проблемы безопасности приложений на Flask. -> Заголовки безопасности".

По умолчанию: None.

PERMANENT_SESSION_LIFETIME:

Параметр PERMANENT_SESSION_LIFETIME определяет срок действия cookie. Если для session.permanent задано значение True, то в будущем, срок действия cookie будет установлен на это количество секунд. Может быть объектом datetime.timedelta или int.

По умолчанию, Flask проверяет, что криптографическая подпись cookie не старше этого значения.

Значение по умолчанию: datetime.timedelta(days=31) - 2678400 секунд.

SESSION_REFRESH_EACH_REQUEST:

Параметр SESSION_REFRESH_EACH_REQUEST контролирует, будет ли cookie отправляться с каждым ответом, если session.permanent имеет значение True. Отправка файла cookie каждый раз (по умолчанию) может более надежно предотвратить истечение срока сессии/сеанса, но требует большей пропускной способности. Непостоянные сеансы не затрагиваются.

По умолчанию: True

USE_X_SENDFILE:

Параметр USE_X_SENDFILE устанавливает заголовок X-Sendfile, при обслуживании файлов сторонним сервером.

Некоторые веб-серверы, такие как Apache, распознают это и обрабатывают файлы более эффективно своими механизмами, освобождая от этого Flask. В противном случае файлы, будут обслуживаются средствами Flask.

Параметр USE_X_SENDFILE имеет смысл только при настройке такого сервера.

По умолчанию: False.

SEND_FILE_MAX_AGE_DEFAULT:

Параметр SEND_FILE_MAX_AGE_DEFAULT, при обслуживании файлов, устанавливает максимальный возраст кеша на это количество секунд. Может быть объектом datetime.timedelta или int. Можно переопределять это значение для каждого файла, используя метод объекта приложения app.get_send_file_max_age() или объекта схемы blueprint.

Если None, то функция flask.send_file() сообщает браузеру, что вместо временного кеша будут использоваться условные запросы, что обычно предпочтительнее.

По умолчанию: None.

SERVER_NAME:

Параметр SERVER_NAME сообщает, к какому хосту и порту привязано веб-приложению. Требуется для поддержки сопоставления маршрута поддомена.

Если SESSION_COOKIE_DOMAIN не установлен, то cookie сессии/сеанса будет использоваться SERVER_NAME . Современные веб-браузеры не позволяют устанавливать cookie для доменов без точки. Чтобы использовать домен локально, необходимо добавить имена хостов, которые должны маршрутизировать приложение, в файл hosts компьютера.

Например:

127.0.0.1 localhost.dev

Если SERVER_NAME установлен, то функция flask.url_for может генерировать внешние URL-адреса только с контекстом приложения, а не с контекстом запроса.

По умолчанию: None.

APPLICATION_ROOT:

Параметр APPLICATION_ROOT сообщает Flask, по какому пути монтируется приложение веб-сервером. Это используется для генерации URL-адресов вне контекста запроса. Внутри запроса, диспетчер отвечает за установку SCRIPT_NAME. Примеры конфигурации диспетчеризации смотрите в разделе "Диспетчеризация веб-приложений на Flask".

Если не установлен SESSION_COOKIE_PATH, то APPLICATION_ROOT будет использоваться для пути cookie сессии/сеанса.

По умолчанию: '/'.

PREFERRED_URL_SCHEME:

Параметр PREFERRED_URL_SCHEME отвечает за схему для создания внешних URL-адресов, когда они не находятся в контексте запроса.

По умолчанию: 'http'.

MAX_CONTENT_LENGTH:

Параметр MAX_CONTENT_LENGTH не позволяет читать входящий запрос, размер которого, больше этого количества байтов. Если не задан и в запросе не указан CONTENT_LENGTH, то данные не будут прочитаны в целях безопасности.

По умолчанию: None.

JSON_AS_ASCII:

Внимание! Параметр удален с версии Flask 2.3.0

Параметр JSON_AS_ASCII отвечает за сериализацию объектов в JSON с кодировкой ASCII. Если JSON_AS_ASCII отключен (False), то JSON, возвращаемый из jsonify, будет содержать символы Unicode. Это влияет на безопасность при рендеринге JSON в JavaScript в шаблонах и обычно должно оставаться включенным.

По умолчанию: True.

JSON_SORT_KEYS:

Внимание! Параметр удален с версии Flask 2.3.0

Параметр JSON_SORT_KEYS сортирует ключи объектов JSON по алфавиту. Это полезно для кеширования, так как обеспечивает одинаковую сериализацию данных, независимо от того, какой хэш-код используется Python. Хотя это не рекомендуется, но можно отключить этот параметр для возможного повышения производительности за счет кеширования.

По умолчанию: True

JSONIFY_PRETTYPRINT_REGULAR:

Внимание! Параметр удален с версии Flask 2.3.0

Если параметр JSONIFY_PRETTYPRINT_REGULAR имеет значение True, то ответы jsonify будут выводиться с символами новой строки \n, пробелами и отступами для облегчения чтения людьми. Всегда включен в режиме отладки.

По умолчанию: False

JSONIFY_MIMETYPE:

Внимание! Параметр удален с версии Flask 2.3.0

Параметр JSONIFY_MIMETYPE указывает тип mimetype ответов jsonify.

По умолчанию: 'application/json'.

TEMPLATES_AUTO_RELOAD:

Параметр TEMPLATES_AUTO_RELOAD отвечает за обновление шаблонов, когда они редактируются. Если этот ключ не установлен, то будет включен автоматически в режиме отладки.

По умолчанию: None.

EXPLAIN_TEMPLATE_LOADING:

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

По умолчанию: False

MAX_COOKIE_SIZE:

Параметр MAX_COOKIE_SIZE предупреждает, если заголовки файлов cookie превышают это количество байтов. По умолчанию - 4093. Большие файлы cookie могут игнорироваться браузерами. Установите 0, чтобы отключить предупреждение.