Argenta/docs/root/flags.rst

.. _root_flags:

Флаги вводимых команд
=====================

Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением. 

Зачем нужны флаги в командах
----------------------------

Управление поведением команды
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

Опциональность и удобство
~~~~~~~~~~~~~~~~~~~~~~~~~

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

Когда могут понадобиться флаги
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Переключение режимов работы**
  Команда выполняет развёртывание приложения обычно, но нужен режим без фактического развёртывания (dry-run) для проверки. Флаг ``--dry-run`` переключит режим работы.

**Настройка уровня детальности**
  При отладке или анализе требуется больше информации о процессе выполнения команды. Флаги ``--verbose`` или ``--debug`` предоставляют подробный вывод.

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

**Форматирование вывода**
  Команда выводит данные текстом, но в некоторых сценариях нужен JSON или CSV. Флаг ``--format=json`` переключит формат вывода.

**Комбинирование опций**
  Часто нужна комбинация нескольких изменений: подробный вывод, dry-run режим и JSON формат. Несколько флагов решают эту задачу одновременно.

Практическое значение
~~~~~~~~~~~~~~~~~~~~~

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

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

-----

Синтаксис флагов
-----------------

Общий синтаксис выглядит так:

.. code-block:: py

   <command_name> <flag_prefix: Literal['-', '--', '---']><flag_name> <flag_value: Optional>

Флаг состоит из префикса (``-``, ``--`` или ``---``), имени и, опционально, значения, которое указывается через пробел.

-----

Два типа флагов
---------------

Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды.

.. note::
    Ошибки валидации не выбрасывают исключений. Вместо этого у каждого объекта :ref:`InputFlag <root_api_command_input_flag>` есть атрибут ``status``, по которому можно определить, прошла ли валидация успешно. Подробное описание API для создания флагов находится в разделе :ref:`Flag <root_api_command_flag>`.

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

-----

Флаги против аргументов
-----------------------

В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением и имеют принципиально разные сферы действия.

Определение и назначение
~~~~~~~~~~~~~~~~~~~~~~~~

**Аргументы** — это параметры, передаваемые при запуске приложения один раз при инициализации. Они определяют глобальное состояние и конфигурацию приложения на протяжении всей его работы, например адрес базы данных, уровень логирования или режим работы.

.. seealso:: API и более подробное описание в разделах :ref:`ArgParser <root_api_orchestrator_argparser>` и :ref:`Arguments <root_api_orchestrator_arguments>`.

**Флаги** — это параметры командных операций, доступные в рамках интерактивной сессии при вводе каждой новой команды. Они позволяют модифицировать поведение конкретной команды без перезагрузки приложения.

.. seealso:: API и более подробное описание в разделе :ref:`Flag <root_api_command_flag>`.

-----

Ключевые различия
~~~~~~~~~~~~~~~~~

**Время жизни и область действия**
  Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы(скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**.

**Частота изменения**
  Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения.

**Уровень конфигурации**
  Аргументы управляют глобальной конфигурацией приложения и его окружением. Флаги управляют поведением отдельных команд и операций пользователя.

**Использование**
  Аргументы задают начальное состояние системы: что подключить, как работать. Флаги управляют тактикой выполнения команд: как её выполнить, с какими изменениями.

-----
  
Практические примеры в Argenta
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

При запуске приложения Argenta передаются аргументы:

- Адрес подключения к базе данных
- Режим работы (production, development, testing)
- Уровень логирования
- Путь к конфигурационным файлам

В интерактивной сессии для каждой команды указываются флаги:

- ``deploy --verbose --dry-run`` — для текущей команды развёртывания
- ``backup --compress --encrypted`` — для команды резервного копирования
- ``test --parallel --coverage`` — для команды тестирования

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