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

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

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

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

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

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

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

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

Переключение режимов работы

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

Настройка уровня детальности

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

Управление поведением при ошибках

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

Форматирование вывода

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

Комбинирование опций

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

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

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

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

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

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

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

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

Примеры:

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

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

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

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

 1from argenta import Router, Response
 2from argenta.command import Command, Flag
 3
 4router = Router()
 5
 6
 7@router.command(Command("greet", flags=Flag("name")))
 8def greet_handler(response: Response):
 9    # Get flag by name
10    name_flag = response.input_flags.get_flag_by_name("name")
11
12    # Check if flag was passed
13    if name_flag:
14        print(f"Hello, {name_flag.input_value}!")
15    else:
16        print("Hello, stranger!")

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

 1from argenta import Router, Response
 2from argenta.command import Command, Flag, PossibleValues
 3from argenta.command.flag import ValidationStatus
 4
 5router = Router()
 6
 7
 8@router.command(Command("deploy", flags=Flag("verbose", possible_values=PossibleValues.NEITHER)))
 9def deploy_handler(response: Response):
10    # Check for toggle flag presence
11    verbose_flag = response.input_flags.get_flag_by_name("verbose")
12
13    if verbose_flag and verbose_flag.status == ValidationStatus.VALID:
14        print("Deploying with verbose output...")
15        # Detailed logic
16    elif verbose_flag and verbose_flag.status == ValidationStatus.INVALID:
17        print("Incorrect flag value")
18        return
19    else:
20        print("Deploying...")
21        # Normal logic

См. также

Подробнее о работе с объектом InputFlags см. в разделе InputFlags.

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

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

  1. Флаги со значениями — принимают параметр после имени флага (например, --name John, --port 8080)

  2. Флаги-переключатели — не принимают значения, их наличие само по себе является сигналом (например, --verbose, --force)

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

Примечание

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

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

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

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

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

См. также

API и более подробное описание в разделах ArgParser и Arguments.

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

См. также

API и более подробное описание в разделе Flag.

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

Время жизни

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

Изменяемость

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

Назначение

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

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

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

  • Адрес подключения к базе данных

  • Режим работы (production, development, testing)

  • Уровень логирования

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

  • deploy --verbose --dry-run — для команды развёртывания

  • backup --compress --encrypted — для команды резервного копирования

  • test --parallel --coverage — для команды тестирования