AI Hints & Edge Cases

Справочник для LLM по специфическим особенностям и "подводным камням" библиотеки chutils.

[!IMPORTANT] При написании кода и решении задач всегда обращайтесь к Банку few-shot примеров (docs/ai_examples/). В нем представлены готовые пары правильных и ошибочных паттернов для обработки ошибок, конфигурации и логирования в контексте стандартов chutils.

1. Строгие правила (Strict Rules)

• Контекст логирования: Всегда используйте bind_context для передачи сквозных идентификаторов (request_id, user_id). Не передавайте их вручную в каждое сообщение лога.
• Секреты: Если вам нужно получить пароль, сначала проверьте его наличие через SecretManager. Никогда не предлагайте пользователю записывать пароль в config.yml.
• Типизация: При доступе к конфигу предпочитайте get_config_int, get_config_boolean и т.д. вместо универсального get_config_value с ручным приведением типов.
• Строгий режим: Для критических параметров всегда передавайте параметр required=True в геттеры (например, get_config_value("Database", "url", required=True)). Это позволит приложению упасть на старте (Fail-Fast) с ошибкой ConfigKeyNotFoundError при отсутствии настройки, вместо тихого продолжения работы со значением None/пустой строкой.

2. Пограничные случаи (Edge Cases)

Hot-Reload Конфигурации

Если включен start_config_watcher(), конфигурация обновляется в памяти автоматически при изменении файла.

• Внимание: Объекты, которые уже были созданы с использованием старых значений (например, соединения с БД), не обновятся сами. Нужно использовать коллбэк on_config_change.

Асинхронность

• Функции aget_config и asave_config_value являются корутинами. При работе в asyncio окружении используйте их для избежания блокировки event loop при I/O операциях с диском.

Маскировка (Masking)

Логгер автоматически маскирует значения, ключи которых похожи на секреты (password, token, secret).

• Если вы выводите объект целиком (например, logger.info(f"User data: {user_dict}")), убедитесь, что чувствительные поля не попадут в лог в открытом виде, если они не входят в стандартный список маскировки.

3. Распространенные ошибки

• Ошибка: Попытка импортировать из chutils.config.core.
• Правильно: Почти всё публичное API доступно напрямую из корня пакета: from chutils import .... Используйте ленивый импорт из корня для чистоты кода.