.. _root_flags: Флаги вводимых команд ===================== Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением. Зачем нужны флаги в командах ---------------------------- Управление поведением команды ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Основная цель флагов — предоставить способ изменить логику работы команды без её переработки. Команда может работать в нескольких режимах: стандартном, подробном, отладочном или упрощённом. Флаги переключают эти режимы по требованию пользователя, оставляя основную функциональность неизменной. Опциональность и удобство ~~~~~~~~~~~~~~~~~~~~~~~~~ Флаги решают проблему обязательности параметров. Если все параметры команды сделать обязательными, это затруднит использование команды. Флаги же позволяют задать значения только необходимые в конкретной ситуации, остальные используют значения по умолчанию. Когда могут понадобиться флаги ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Переключение режимов работы** Команда выполняет развёртывание приложения обычно, но нужен режим без фактического развёртывания (dry-run) для проверки. Флаг ``--dry-run`` переключит режим работы. **Настройка уровня детальности** При отладке или анализе требуется больше информации о процессе выполнения команды. Флаги ``--verbose`` или ``--debug`` предоставляют подробный вывод. **Управление поведением при ошибках** По умолчанию команда может прерваться при первой ошибке. Флаг ``--force`` позволит продолжить работу, пропуская некритичные ошибки. **Форматирование вывода** Команда выводит данные текстом, но в некоторых сценариях нужен JSON или CSV. Флаг ``--format=json`` переключит формат вывода. **Комбинирование опций** Часто нужна комбинация нескольких изменений: подробный вывод, dry-run режим и JSON формат. Несколько флагов решают эту задачу одновременно. Практическое значение ~~~~~~~~~~~~~~~~~~~~~ Флаги делают команды более предсказуемыми и контролируемыми. Пользователь может начать с простого использования, а затем добавлять флаги по мере необходимости. Это особенно важно при автоматизации задач в скриптах, где гибкость интерфейса критична. Флаги также облегчают интеграцию команд в различные системы, так как дополнительное поведение достигается без изменения структуры команды, а только через передачу опциональных параметров. ----- Синтаксис флагов ----------------- Общий синтаксис выглядит так: .. code-block:: py Флаг состоит из префикса (``-``, ``--`` или ``---``), имени и, опционально, значения, которое указывается через пробел. ----- Два типа флагов --------------- Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды. .. note:: Ошибки валидации не выбрасывают исключений. Вместо этого у каждого объекта :ref:`InputFlag ` есть атрибут ``status``, по которому можно определить, прошла ли валидация успешно. Подробное описание API для создания флагов находится в разделе :ref:`Flag `. При регистрации флага можно задать правила валидации для его значения. По умолчанию любое значение считается корректным. Валидацию можно настроить несколькими способами: ----- Флаги против аргументов ----------------------- В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением и имеют принципиально разные сферы действия. Определение и назначение ~~~~~~~~~~~~~~~~~~~~~~~~ **Аргументы** — это параметры, передаваемые при запуске приложения один раз при инициализации. Они определяют глобальное состояние и конфигурацию приложения на протяжении всей его работы, например адрес базы данных, уровень логирования или режим работы. .. seealso:: API и более подробное описание в разделах :ref:`ArgParser ` и :ref:`Arguments `. **Флаги** — это параметры командных операций, доступные в рамках интерактивной сессии при вводе каждой новой команды. Они позволяют модифицировать поведение конкретной команды без перезагрузки приложения. .. seealso:: API и более подробное описание в разделе :ref:`Flag `. ----- Ключевые различия ~~~~~~~~~~~~~~~~~ **Время жизни и область действия** Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы (скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**. **Частота изменения** Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения. **Уровень конфигурации** Аргументы управляют глобальной конфигурацией приложения и его окружением. Флаги управляют поведением отдельных команд и операций пользователя. **Использование** Аргументы задают начальное состояние системы: что подключить, как работать. Флаги управляют тактикой выполнения команд: как её выполнить, с какими изменениями. ----- Практические примеры в Argenta ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ При запуске приложения Argenta передаются аргументы: - Адрес подключения к базе данных - Режим работы (production, development, testing) - Уровень логирования - Путь к конфигурационным файлам В интерактивной сессии для каждой команды указываются флаги: - ``deploy --verbose --dry-run`` — для текущей команды развёртывания - ``backup --compress --encrypted`` — для команды резервного копирования - ``test --parallel --coverage`` — для команды тестирования Один пользователь может выполнить разные команды с разными флагами в одной сессии приложения, без необходимости перезапуска с новыми аргументами.