Python Pydantic Settings Config Writing

Конфигурация через pydantic-settings

Порядок работы

1. Извлечь точные поля, типы, обязательность, источники и приоритеты.
2. Предложить пользователю значения по умолчанию для параметров, у которых есть безопасное ожидаемое значение; не назначать их без согласования и не добавлять остальные несогласованные поля.
3. Разделить top-level settings worker-а, общий runtime, настройки каждой задачи и вложенные технологические блоки.
4. Реализовать immutable-модели, loader и startup preflight.
5. Обновить минимальный и полный YAML-примеры, а также затронутую deployment-конфигурацию.
6. Проверить модели, источники, примеры, ошибки загрузки и preflight тестами.

Граница ответственности

• Конфигурация является infrastructure-адаптером и не импортируется из domain или application.
• Settings содержат данные и чистые производные значения, но не создают pool, client, worker, logger и другие runtime-ресурсы.
• Adapter factory преобразует settings в точные kwargs клиента; не передавать model_dump() вслепую.
• Сетевые проверки, чтение секретов и writable-проверки не выполнять в pydantic validators.
• Не определять поля и defaults, отсутствующие в требованиях.

Структура

Для малого сервиса допустима плоская структура:

infrastructure/config/
├── __init__.py
├── base.py
├── workers.py
├── postgres.py
└── nats.py

При более чем трёх top-level worker settings либо смешении несвязанных зависимостей перейти к:

infrastructure/config/
├── __init__.py
├── base.py
├── worker/
│   ├── api.py
│   ├── nats_consumer.py
│   └── publisher.py
├── postgres.py
└── nats.py

• base.py содержит общие базовые модели, loader и source strategy.
• Один top-level worker config композирует только нужные ему concern-блоки.
• Общий runtime-блок содержит только параметры lifecycle всего процесса. Интервал, timeout операции, задержка по результату, progress heartbeat и readiness принадлежат блоку конкретной долгоживущей задачи.
• Для нескольких задач создавать отдельный блок каждой задачи. Не поднимать их параметры в общий блок только потому, что текущие значения совпадают.
• Для стандартных файловых probe headless worker-а хранить heartbeat_file, readiness_file и heartbeat_timeout_ms в блоке задачи-владельца. Пути оставлять обязательными, безопасный timeout предлагать пользователю как default.
• Concern-модуль называть по технологии: postgres.py, а не общий db.py.
• __init__.py содержит только re-export и алфавитный __all__.
• Не выполнять массовое перемещение автоматически в небольшой задаче.

Модели

Два уровня

• Только top-level worker settings наследуется от BaseSettings.
• Вложенные concern-блоки наследуются от общей immutable BaseModel.
• Не вкладывать BaseSettings в BaseSettings.

Неизменяемость и строгость

• Использовать frozen=True, extra="forbid", strict=True и validate_default=True.
• Использовать tuple, а не list, для коллекций.
• Не менять settings после загрузки и не применять model_copy(update=...) как runtime reload.
• Для env-источника отдельно реализовать контролируемое преобразование строк: строгая YAML-валидация не означает произвольную env-coercion.
• Неизвестный ключ и неверный тип должны останавливать запуск.

Обязательность

• Обязательный блок объявлять без default_factory:

  postgres: PostgresSettings
  

• default_factory использовать только для полностью необязательного блока с безопасными defaults.

• Адреса внешних систем, имена БД/stream-ов, пользователи и важные пути не угадывать.

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

Подробности: модели и валидация.

Источники и загрузчик

• Состав и приоритет источников определять требованиями.
• Перечислять источники явно через settings_customise_sources; первый элемент tuple имеет высший приоритет.
• Не смешивать YAML, env, dotenv и secrets автоматически.
• YAML-only через CONFIG_FILE остаётся рекомендуемым вариантом для текущих сервисов, но не универсальным правилом.
• Не читать CONFIG_FILE при импорте модуля.
• Загрузчик при вызове проверяет env, абсолютный путь, существование и читаемость, затем создаёт новый settings-объект.
• Не создавать глобальный settings = ... и не кешировать loader неявно.
• Один worker получает один immutable top-level config в composition root.

Подробности: источники и загрузчик.

Секреты и внешние файлы

• Хранить путь к секрету как обязательный Path.
• Не хранить plaintext в YAML/env, если контракт использует file-based secret.
• Не создавать property с DSN, содержащим открытый пароль.
• Секрет читает отдельный provider при создании клиента; для временного хранения использовать SecretStr.
• Не включать секреты в repr, dump, логи, metrics, traces и health responses.
• Startup preflight проверяет файлы, директории и другие внешние артефакты после структурной валидации.
• Для файловых heartbeat/readiness проверять абсолютные пути и writable-каталоги; healthcheck entrypoint не выполняет этот preflight повторно.
• Ротация требует явного перечитывания и пересоздания зависимого клиента/pool; property с повторным чтением файла сама по себе ротацию не обеспечивает.

Подробности: секреты и preflight.

Валидация

• Простые ограничения задавать через Annotated и Field.
• field_validator использовать для необходимой нормализации одного поля.
• model_validator(mode="after") использовать для связей нескольких полей.
• Проверять min_size <= max_size и другие заданные взаимосвязи.
• Единицы выражать timedelta либо явным суффиксом _ms, _seconds, _bytes и т. п. В одном контракте не смешивать сокращённое и полное обозначение одной единицы.
• Конечные наборы задавать StrEnum или Literal, а не свободным str.
• Не нормализовать значимое значение без требования.
• Собственные сообщения об ошибках писать по-русски без исходных секретов.

Совместимость

• Считать имена и типы полей deployment-контрактом worker-а.
• При добавлении обязательного поля обновлять все затронутые examples и manifests.
• Переименование/удаление согласовывать с порядком развёртывания.
• Временный alias добавлять только на обозначенный переходный период.
• Одновременную передачу старого и нового имени считать ошибкой.
• Не менять единицу измерения под прежним именем поля.

Документирование конфигурации

• Для каждого top-level worker settings поддерживать два валидных примера: минимальный — только обязательные поля, полный — все доступные поля явно.
• Существующий *.worker.example.yaml считать минимальным примером, а полный называть *.worker.full.example.yaml.
• В минимальном примере не повторять поля с defaults: он показывает достаточный контракт запуска и делает изменение обязательности заметным.
• В полном примере явно указывать также default-поля и необязательные блоки: он служит каталогом доступных настроек, а не альтернативным источником defaults.
• Использовать безопасные демонстрационные значения и пути к файлам секретов; plaintext-секреты и значения production-среды не публиковать.
• Оба примера загружать тем же loader-ом и валидировать тем же классом settings, который использует worker.
• README может кратко описывать способ передачи конфигурации и ссылаться на эти файлы, но схема полей и правила примеров принадлежат этому скилу.

Конфигурация логера и ошибки

• Не логировать model_dump() целиком.
• Разрешено описывать и валидировать типизированные параметры логера и явно преобразовывать их в настройки logging adapter-а.
• Settings, loader, preflight и adapter factory не создают записей в логах.
• Loader/preflight не подавляют ошибки и не переходят к defaults после сбоя.
• Loader/preflight возвращают или пробрасывают ошибку с безопасным контекстом и ничего не логируют.
• Завершать процесс до создания runtime-ресурсов.

Примеры технологий

Читать только относящийся к задаче материал:

• PostgreSQL, пул psycopg и yoyo
• NATS и JetStream
• FastAPI, Uvicorn и CORS
• Логирование
• Worker подписок
• Runtime и независимые фоновые задачи
• Шаблон новой технологии

Примеры являются предложением полей, а не контрактом. Сверять параметры с официальным API установленной версии. Не добавлять все параметры клиента на будущее.

Тестирование

• Создавать модели обычной валидацией; не использовать model_construct() как стандартную фикстуру.
• Отдельно тестировать structural validation, source priority и preflight.
• Параметризованно загружать минимальный и полный *.example.yaml соответствующим классом.
• Проверять неизвестный ключ, неверный тип, отсутствие обязательной секции, повреждённый YAML и недоступный внешний файл.
• Проверять immutable-модели и отсутствие mutable collections.
• Использовать tmp_path для preflight file tests.
• Не проверять внутреннюю реализацию pydantic-settings.

Антипаттерны

• BaseSettings во вложенном блоке.
• Mutable settings и коллекции.
• extra="ignore" внутри выбранного worker config.
• getenv() в class body или module-level settings instance.
• Field(default_factory=...) для обязательной внешней зависимости.
• Production-sensitive default, похожий на рабочее значение.
• I/O или создание клиента в validator/property.
• Полный DSN с паролем в обычной строке.
• model_dump() конфигурации в логах.
• Автоматическое смешение источников.
• model_construct() как основной путь тестирования.
• Универсальный config.py со всеми технологиями и worker-ами.
• Общий operation_timeout, interval или retry delay для независимых задач.

Критерии готовности

• Реализованы только согласованные поля и источники.
• Top-level и вложенные модели глубоко неизменяемы.
• Неизвестные поля запрещены, defaults валидируются.
• Обязательные блоки нельзя пропустить.
• Loader не читает env во время импорта.
• Секреты не материализуются в serializable settings.
• Preflight отделён от structural validation.
• Клиентские kwargs строятся явным adapter factory.
• Для каждого worker-а минимальный и полный примеры проходят валидацию и не содержат plaintext-секреты.
• Изменение deployment-контракта отражено во всех потребителях.
• Unit-тесты и проверки репозитория прошли.

Материалы

• Модели и валидация
• Источники и загрузчик
• Секреты и preflight
• Чеклисты