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

Основы конфигурации

Атрибут config фактически является подклассом словаря и может быть изменен, как любой словарь:

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

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

app.testing = True

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

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

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

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

$ flask --app hello run --debug

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

Встроенные значения конфигурации

Следующие значения конфигурации используются внутри Flask:

DEBUG

Включен ли режим отладки. При использовании flask run для запуска сервера разработки, при возникновении необработанных исключений будет показан интерактивный отладчик, а сервер будет перезагружен при изменении кода. Атрибут debug сопоставляется с этим ключом конфигурации. Это устанавливается переменной среды FLASK_DEBUG. Возможно, он не будет работать как ожидается, если установлен в коде.

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

Значение по умолчанию: False

TESTING

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

Значение по умолчанию: False

PROPAGATE_EXCEPTIONS

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

Значение по умолчанию: None

TRAP_HTTP_EXCEPTIONS

Если для исключения типа HTTPException нет обработчика, он поднимается повторно для обработки интерактивным отладчиком вместо возврата простого ответа об ошибке.

Значение по умолчанию: False

TRAP_BAD_REQUEST_ERRORS

Попытка получить несуществующий ключ из словарей запросов, таких как args и form, вернёт страницу ошибки 400 Bad Request. Включите это, чтобы рассматривать ошибку как необработанное исключение, чтобы получить интерактивный отладчик. Это более специфичная версия TRAP_HTTP_EXCEPTIONS. Если не установлено, оно включено в режиме отладки.

Значение по умолчанию: None

SECRET_KEY

Секретный ключ, который будет использоваться для безопасного шифрования cookie сессии и может быть использован для других задач безопасности расширениями или вашим приложением. Он должен быть длинным случайным bytes или str. Например, скопируйте вывод этого в свою конфигурацию:

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

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

Значение по умолчанию: None

SECRET_KEY_FALLBACKS

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

Ключи должны быть удалены после соответствующего периода времени, так как проверка каждого дополнительного ключа добавляет некоторую нагрузку.

Встроенная безопасная сессия cookie Flask поддерживает это. Расширения, использующие SECRET_KEY, пока могут не поддерживать это.

Значение по умолчанию: None

Добавлена в версии 3.1.

SESSION_COOKIE_NAME

Имя cookie сессии. Можно изменить, если у вас уже есть cookie с таким же именем.

Значение по умолчанию: 'session'

SESSION_COOKIE_DOMAIN

Значение параметра Domain в cookie сессии. Если не задано, браузеры отправят cookie только на точный домен, с которого он был установлен. В противном случае они отправят его и на любые поддомены заданного значения.

Не устанавливать это значение более ограничено и безопасно, чем установка.

Значение по умолчанию: None

Предупреждение

Если это изменится после того, как браузер создал cookie с другим значением, это может привести к созданию другого. Браузеры могут отправлять оба в неопределённом порядке. В этом случае вы можете изменить SESSION_COOKIE_NAME или каким-либо другим способом аннулировать старые сессии.

Журнал изменений

Изменено в версии 2.3: Не установлено по умолчанию, не использует SERVER_NAME по умолчанию.

SESSION_COOKIE_PATH

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

Значение по умолчанию: None

SESSION_COOKIE_HTTPONLY

Браузеры не позволят JavaScript получать доступ к cookie, помеченным как «HTTP-only», для повышения безопасности.

Значение по умолчанию: True

SESSION_COOKIE_SECURE

Браузеры будут отправлять cookie только с запросами по HTTPS, если cookie помечен как «secure». Приложение должно быть доступно по HTTPS, для того чтобы это имело смысл.

Значение по умолчанию: False

SESSION_COOKIE_PARTITIONED

Браузеры будут отправлять cookie на основе домена верхнего уровня документа, а не только домена документа, устанавливающего cookie. Это предотвращает «утечку» cookie третьей стороны, установленных во фреймах, между различными сайтами.

Браузеры начинают отключать неразделенные cookie третьей стороны, поэтому необходимо помечать cookie как разделенные, если вы ожидаете их работоспособности в таких встроенных ситуациях.

Включение этого подразумевает также включение SESSION_COOKIE_SECURE, так как оно работает только при доступе по HTTPS.

Значение по умолчанию: False

Добавлена в версии 3.1.

SESSION_COOKIE_SAMESITE

Ограничить, как cookie отправляются с запросами с внешних сайтов. Может быть установлено в 'Lax' (рекомендуется) или 'Strict'. См. Параметры Set-Cookie.

Значение по умолчанию: None

Журнал изменений

Добавлена в версии 1.0.

PERMANENT_SESSION_LIFETIME

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

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

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

SESSION_REFRESH_EACH_REQUEST

Управлять отправкой cookie с каждым ответом, когда session.permanent имеет значение true. Отправка cookie каждый раз (по умолчанию) более надёжно предотвращает истечение сессии, но использует больше пропускной способности. На непостоянные сессии это не влияет.

Значение по умолчанию: True

USE_X_SENDFILE

При обслуживании файлов установить заголовок X-Sendfile вместо отправки данных с Flask. Некоторые веб-серверы, такие как Apache, распознают это и обслуживают данные более эффективно. Это имеет смысл только при использовании такого сервера.

Значение по умолчанию: False

SEND_FILE_MAX_AGE_DEFAULT

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

Если None, send_file указывает браузеру использовать условные запросы вместо кэша с определённым временем, что обычно предпочтительнее.

Значение по умолчанию: None

TRUSTED_HOSTS

Проверить Request.host и другие атрибуты, которые используют его, на соответствие этим доверенным значениям. Вызовите SecurityError, если хост недействителен, что приводит к ошибке 400. Если это None, все хосты действительны. Каждое значение совпадает точно или может начинаться с точки . для соответствия любому поддомену.

Проверка выполняется во время маршрутизации по этому значению. before_request и after_request колбеки всё равно будут вызваны.

Значение по умолчанию: None

Добавлена в версии 3.1.

SERVER_NAME

Укажите приложению хост и порт, к которым оно привязано.

Должно быть установлено, если subdomain_matching включено, чтобы можно было извлечь поддомен из запроса.

Должно быть установлено для url_for генерации внешних URL-адресов за пределами контекста запроса.

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

Изменено в версии 3.1: Не ограничивает запросы только этим доменом для subdomain_matching и host_matching.

Изменения

Изменено в версии 2.3: Не влияет на SESSION_COOKIE_DOMAIN.

Изменено в версии 1.0: Не включает subdomain_matching неявно.

APPLICATION_ROOT

Укажите приложению путь, под которым оно смонтировано приложением/веб-сервером. Это используется для генерации URL-адресов за пределами контекста запроса (внутри запроса за настройку SCRIPT_NAME отвечает диспетчер; см. Отправка приложения для примеров конфигурации диспетчера).

Будет использоваться для пути куки сессии, если SESSION_COOKIE_PATH не задан.

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

PREFERRED_URL_SCHEME

Используйте эту схему для генерации внешних URL-адресов, когда вы не находитесь в контексте запроса.

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

MAX_CONTENT_LENGTH

Максимальное количество байтов, которое будет считано во время этого запроса. Если этот предел превышен, возникает ошибка 413 RequestEntityTooLarge. Если значение установлено в None, ограничение на уровне приложения Flask не применяется. Однако, если это None, запрос не имеет заголовка Content-Length, а WSGI-сервер не указывает, что он завершает поток, то данные не считываются, чтобы избежать бесконечного потока.

Каждый запрос по умолчанию использует эту конфигурацию. Ее можно установить для определённого Request.max_content_length, чтобы применить ограничение к этому конкретному представлению. Значение должно быть установлено в соответствии со специфическими потребностями приложения или представления.

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

Изменения

Добавлен в версии 0.6.

MAX_FORM_MEMORY_SIZE

Максимальный размер в байтах любого поля формы без файла в теле multipart/form-data. Если этот предел превышен, возникает ошибка 413 RequestEntityTooLarge. Если значение установлено в None, ограничение на уровне приложения Flask не применяется.

Каждый запрос по умолчанию использует эту конфигурацию. Ее можно установить для определённого Request.max_form_memory_parts , чтобы применить ограничение к этому конкретному представлению. Значение должно быть установлено в соответствии со специфическими потребностями приложения или представления.

По умолчанию: 500_000

Добавлен в версии 3.1.

MAX_FORM_PARTS

Максимальное количество полей, которые могут присутствовать в теле multipart/form-data. Если этот предел превышен, возникает ошибка 413 RequestEntityTooLarge. Если значение установлено в None, ограничение на уровне приложения Flask не применяется.

Каждый запрос по умолчанию использует эту конфигурацию. Ее можно установить для определённого Request.max_form_parts, чтобы применить ограничение к этому конкретному представлению. Значение должно быть установлено в соответствии со специфическими потребностями приложения или представления.

По умолчанию: 1_000

Добавлен в версии 3.1.

TEMPLATES_AUTO_RELOAD

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

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

EXPLAIN_TEMPLATE_LOADING

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

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

MAX_COOKIE_SIZE

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

PROVIDE_AUTOMATIC_OPTIONS

Установите в False для отключения автоматического добавления ответов OPTIONS. Это можно переопределить для каждого маршрута, изменив атрибут provide_automatic_options.

Настройка из файлов Python

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

Обычный шаблон выглядит так:

app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')

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

$ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
$ flask run
 * Running on http://127.0.0.1:5000/

$ set -x YOURAPPLICATION_SETTINGS /path/to/settings.cfg
$ flask run
 * Running on http://127.0.0.1:5000/

> set YOURAPPLICATION_SETTINGS=\path\to\settings.cfg
> flask run
 * Running on http://127.0.0.1:5000/

> $env:YOURAPPLICATION_SETTINGS = "\path\to\settings.cfg"
> flask run
 * Running on http://127.0.0.1:5000/

Сами файлы конфигурации — это фактические файлы Python. Только значения, записанные в верхнем регистре, фактически сохраняются в объекте config позднее. Поэтому убедитесь, что для ваших ключей конфигурации используются заглавные буквы.

Вот пример файла конфигурации:

# Example configuration
SECRET_KEY = '192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf'

Убедитесь, что вы загружаете конфигурацию очень рано, чтобы расширения могли получить доступ к конфигурации при запуске. В объекте config также есть другие методы для загрузки из отдельных файлов. Для полной справки прочитайте документацию объекта Config.

Настройка из файлов данных

Также можно загрузить конфигурацию из файла в формате по вашему выбору, используя from_file(). Например, для загрузки из файла TOML:

import tomllib
app.config.from_file("config.toml", load=tomllib.load, text=False)

Или из файла JSON:

import json
app.config.from_file("config.json", load=json.load)

Настройка из переменных среды

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

Переменные среды можно установить в оболочке перед запуском сервера:

$ export FLASK_SECRET_KEY="5f352379324c22463451387a0aec5d2f"
$ export FLASK_MAIL_ENABLED=false
$ flask run
 * Running on http://127.0.0.1:5000/

$ set -x FLASK_SECRET_KEY "5f352379324c22463451387a0aec5d2f"
$ set -x FLASK_MAIL_ENABLED false
$ flask run
 * Running on http://127.0.0.1:5000/

> set FLASK_SECRET_KEY="5f352379324c22463451387a0aec5d2f"
> set FLASK_MAIL_ENABLED=false
> flask run
 * Running on http://127.0.0.1:5000/

> $env:FLASK_SECRET_KEY = "5f352379324c22463451387a0aec5d2f"
> $env:FLASK_MAIL_ENABLED = "false"
> flask run
 * Running on http://127.0.0.1:5000/

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

app.config.from_prefixed_env()
app.config["SECRET_KEY"]  # Is "5f352379324c22463451387a0aec5d2f"

Префикс по умолчанию FLASK_. Он настраивается через аргумент prefix метода from_prefixed_env().

Значения будут анализироваться для попытки преобразования их в тип, более специфичный, чем строки. По умолчанию используется json.loads(), поэтому возможны любые допустимые значения JSON, включая списки и словари. Это настраивается через аргумент loads метода from_prefixed_env().

При добавлении логического значения с помощью анализа JSON по умолчанию допустимыми значениями являются только «true» и «false», в нижнем регистре. Имейте в виду, что любая непустая строка считается True в Python.

Можно задавать ключи вложенных словарей, разделяя ключи двойным подчеркиванием (__). Любые промежуточные ключи, которых нет в родительском словаре, будут инициализированы пустым словарем.

$ export FLASK_MYAPI__credentials__username=user123

app.config["MYAPI"]["credentials"]["username"]  # Is "user123"

В Windows ключи переменных среды всегда записываются в верхнем регистре, поэтому приведенный выше пример приведёт к MYAPI__CREDENTIALS__USERNAME.

Для ещё более широких возможностей загрузки конфигурации, включая слияние и поддержку регистронезависимых ключей в Windows, попробуйте специализированную библиотеку, такую как Dynaconf, которая включает интеграцию с Flask.

Рекомендации по настройке

Недостатком подхода, упомянутого ранее, является то, что он немного усложняет тестирование. В общем случае нет единственного 100%-ного решения этой проблемы, но есть несколько моментов, которые следует учитывать для улучшения этого опыта:

1. Создайте своё приложение в функции и регистрируйте шаблоны в нём. Таким образом, вы можете создавать несколько экземпляров своего приложения с различными прикреплёнными конфигурациями, что значительно упрощает тестирование. Вы можете использовать это для передачи конфигурации по мере необходимости.
2. Не пишите код, которому требуется конфигурация во время импорта. Если ограничиться только доступом к конфигурации во время запросов, вы можете переконфигурировать объект по мере необходимости.
3. Убедитесь, что вы загружаете конфигурацию на очень ранней стадии, чтобы расширения могли получить доступ к конфигурации при вызове init_app.

Разработка/Производство

Большинству приложений требуется более одной конфигурации. Должны быть по меньшей мере отдельные конфигурации для сервера производства и для сервера, используемого во время разработки. Самый простой способ справиться с этим — использовать стандартную конфигурацию, которая всегда загружается и является частью контроля версий, и отдельную конфигурацию, которая переопределяет значения по мере необходимости, как показано в примере выше:

app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')

Затем вам нужно просто добавить отдельный config.py файл и экспортировать YOURAPPLICATION_SETTINGS=/path/to/config.py и всё готово. Однако есть и альтернативные способы. Например, вы можете использовать импорты или наследование.

Что очень популярно в Django, так это явное указание импорта в файле конфигурации, добавив from yourapplication.default_settings import * в начало файла, а затем вручную переопределяя изменения. Вы также можете проверить переменную среды, например YOURAPPLICATION_MODE , и установить её значение на production, development и т.д., и импортировать разные жёстко закодированные файлы на основе этого.

Ещё один интересный способ — использовать классы и наследование для конфигурации:

class Config(object):
    TESTING = False

class ProductionConfig(Config):
    DATABASE_URI = 'mysql://user@localhost/foo'

class DevelopmentConfig(Config):
    DATABASE_URI = "sqlite:////tmp/foo.db"

class TestingConfig(Config):
    DATABASE_URI = 'sqlite:///:memory:'
    TESTING = True

Чтобы включить такую конфигурацию, нужно просто вызвать from_object():

app.config.from_object('configmodule.ProductionConfig')

Обратите внимание, что from_object() не создаёт экземпляр объекта класса. Если вам нужно создать экземпляр класса, например, для доступа к свойству, то нужно сделать это до вызова from_object():

from configmodule import ProductionConfig
app.config.from_object(ProductionConfig())

# Alternatively, import via string:
from werkzeug.utils import import_string
cfg = import_string('configmodule.ProductionConfig')()
app.config.from_object(cfg)

Создание экземпляра объекта конфигурации позволяет использовать @property в ваших классах конфигурации:

class Config(object):
    """Base config, uses staging database server."""
    TESTING = False
    DB_SERVER = '192.168.1.56'

    @property
    def DATABASE_URI(self):  # Note: all caps
        return f"mysql://user@{self.DB_SERVER}/foo"

class ProductionConfig(Config):
    """Uses production database server."""
    DB_SERVER = '192.168.19.32'

class DevelopmentConfig(Config):
    DB_SERVER = 'localhost'

class TestingConfig(Config):
    DB_SERVER = 'localhost'
    DATABASE_URI = 'sqlite:///:memory:'

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

• Храните стандартную конфигурацию в системе контроля версий. Либо заполните конфигурацию этим стандартным значением, либо импортируйте его в свои собственные файлы конфигурации перед переопределением значений.
• Используйте переменную среды для переключения между конфигурациями. Это можно сделать вне интерпретатора Python и значительно упрощает разработку и развертывание, потому что вы быстро и легко можете переключаться между различными конфигурациями, не изменяя код. Если вы часто работаете над разными проектами, вы можете даже создать свою собственную скриптовую утилиту для запуска виртуальной среды и экспорта вашей конфигурации разработки.
• Используйте инструмент, подобный fabric, для одновременной загрузки кода и конфигурации на сервер(ы) производства.

Папки экземпляров

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

С Flask 0.8 был представлен новый атрибут: Flask.instance_path. Он относится к новой концепции — «папке экземпляра». Папка экземпляра предназначена для того, чтобы не находиться под управлением системы контроля версий и быть специфичной для развертывания. Это идеальное место для размещения элементов, которые меняются во время выполнения или конфигурационных файлов.

Вы можете явно указать путь к папке экземпляра при создании приложения Flask или позволить Flask автоматически определить папку экземпляра. Для явного конфигурирования используйте параметр instance_path.

app = Flask(__name__, instance_path='/path/to/instance/folder')

Пожалуйста, имейте в виду, что этот путь обязательно должен быть абсолютным.

Если параметр instance_path не указан, используются следующие значения по умолчанию:

• Модуль не установлен:

  /myapp.py
  /instance
  

• Пакет не установлен:

  /myapp
      /__init__.py
  /instance
  

• Установленный модуль или пакет:

  $PREFIX/lib/pythonX.Y/site-packages/myapp
  $PREFIX/var/myapp-instance
  

  $PREFIX — это префикс вашей установки Python. Это может быть /usr или путь к вашему virtualenv. Вы можете вывести значение sys.prefix для просмотра установленного префикса.

Поскольку объект конфигурации позволял загружать конфигурационные файлы из относительных имен файлов, мы добавили возможность изменять загрузку по именам файлов, относительно пути экземпляра, если это требуется. Поведение относительных путей в конфигурационных файлах может быть переключено между «относительно корня приложения» (по умолчанию) и «относительно папки экземпляра» с помощью переключателя instance_relative_config в конструкторе приложения:

app = Flask(__name__, instance_relative_config=True)

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

app = Flask(__name__, instance_relative_config=True)
app.config.from_object('yourapplication.default_settings')
app.config.from_pyfile('application.cfg', silent=True)

Путь к папке экземпляра можно найти через Flask.instance_path. Flask также предоставляет ярлык для открытия файла из папки экземпляра с помощью Flask.open_instance_resource().

Пример использования обоих методов:

filename = os.path.join(app.instance_path, 'application.cfg')
with open(filename) as f:
    config = f.read()

# or via open_instance_resource:
with app.open_instance_resource('application.cfg') as f:
    config = f.read()