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>

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

**Примеры:**

.. code-block:: shell

   greet --name John
   deploy --verbose
   backup -f --compress

-----

Работа с флагами в обработчиках
--------------------------------

Чтобы получить значение флага в обработчике, используйте объект ``response.input_flags`` типа :ref:`InputFlags <root_api_command_input_flags>`.

**Пример с флагом, имеющим значение:**

.. literalinclude:: ../code_snippets/flags/greet_handler.py
   :language: python
   :linenos:

**Пример с флагом-переключателем:**

.. literalinclude:: ../code_snippets/flags/deploy_handler.py
   :language: python
   :linenos:

.. seealso::
   Подробнее о работе с объектом ``InputFlags`` см. в разделе :ref:`InputFlags <root_api_command_input_flags>`.

-----

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

Флаги бывают двух основных видов:

1. **Флаги со значениями** — принимают параметр после имени флага (например, ``--name John``, ``--port 8080``)
2. **Флаги-переключатели** — не принимают значения, их наличие само по себе является сигналом (например, ``--verbose``, ``--force``)

``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>`.

-----

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

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

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

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

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

Аргументы при запуске приложения:

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

Флаги в интерактивной сессии:

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