InputFlags

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

См. также

Документация по отдельным флагам (Flag, InputFlag)

Документация по InputFlags — коллекция обработанных флагов, введённых пользователем.

Документация по Response — объект ответа, содержащий InputFlags

Общая информация о флагах и их использовании в приложении Argenta

---

Инициализация

__init__(self, flags: list[InputFlag] | None = None) -> None

Создаёт новую коллекцию введённых флагов.

• flags: Необязательный список флагов типа InputFlag для инициализации коллекции. Если не указан, создаётся пустая коллекция.

Предупреждение

Экземпляры этого класса обычно не создаются напрямую. Они автоматически формируются системой при обработке пользовательского ввода и доступны через атрибут input_flags объекта Response.

Атрибуты:

flags

Список всех введённых флагов типа InputFlag. Пуст, если флаги не были переданы при инициализации или пользователь не ввёл их с командой.

Пример использования:

from argenta import Command, Response, Router
from argenta.command import Flag, Flags


router = Router(title="Example")

@router.command(
    Command(
        "example",
        description="Example command with flags",
        flags=Flags([Flag("name"), Flag("age")]),
    )
)
def example_handler(response: Response):
    input_flags = response.input_flags

    if input_flags:
        print(f"Received {len(input_flags)} flag(s)")
    else:
        print("No flags provided")

---

Методы

get_flag_by_name

get_flag_by_name(self, name: str) -> InputFlag | None

Возвращает флаг по имени.

param name:

Имя искомого флага (без префикса).

return:

Объект InputFlag или None, если флаг не найден.

Метод возвращает первый флаг с соответствующим именем (без учёта префикса).

Пример использования:

from argenta import Command, Response, Router
from argenta.command import Flag, Flags

router = Router(title="Get Flag Example")


@router.command(
    Command(
        "config",
        description="Configure settings",
        flags=Flags([Flag("host"), Flag("port"), Flag("debug")]),
    )
)
def config_handler(response: Response):
    input_flags = response.input_flags

    host_flag = input_flags.get_flag_by_name("host")
    port_flag = input_flags.get_flag_by_name("port")
    debug_flag = input_flags.get_flag_by_name("debug")

    if host_flag:
        print(f"Host: {host_flag.input_value}")

    if port_flag:
        print(f"Port: {port_flag.input_value}")

    if debug_flag:
        print("Debug mode enabled")

    missing_flag = input_flags.get_flag_by_name("nonexistent")
    if missing_flag is None:
        print("Flag 'nonexistent' not found")

---

add_flag

add_flag(self, flag: InputFlag) -> None

Добавляет введённый флаг в коллекцию.

param flag:

Флаг типа InputFlag для добавления.

return:

None.

Метод добавляет флаг в конец списка flags. Используется для динамического расширения коллекции.

Примечание

Этот метод используется редко, так как InputFlags обычно создаётся автоматически. Однако он может быть полезен для тестирования или ручного создания коллекций.

Пример использования:

from argenta import Command, Response, Router
from argenta.command.flag import InputFlag, ValidationStatus
from argenta.command import InputFlags

router = Router(title="Add Flag Example")


@router.command(Command("test", description="Test command"))
def test_handler(response: Response):
    # Create new InputFlags collection
    new_flags = InputFlags()

    # Add one flag
    test_flag = InputFlag(
        name="test", prefix="--", input_value="value", status=ValidationStatus.VALID
    )
    new_flags.add_flag(test_flag)

    print(f"Flags count: {len(new_flags.flags)}")
    print(f"First flag: {new_flags.flags[0].name}")

---

add_flags

add_flags(self, flags: list[InputFlag]) -> None

Добавляет в коллекцию список введённых флагов.

param flags:

Список флагов типа InputFlag для добавления.

return:

None.

Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления.

Пример использования:

from argenta.command.flag import InputFlag, ValidationStatus
from argenta.command import InputFlags

# Create InputFlags collection
flags = InputFlags()

# Create several flags
flag1 = InputFlag(name="option1", prefix="--", input_value="value1", status=ValidationStatus.VALID)

flag2 = InputFlag(name="option2", prefix="--", input_value="value2", status=ValidationStatus.VALID)

flag3 = InputFlag(name="option3", prefix="---", input_value="value3", status=ValidationStatus.VALID)

# Add all flags in one call
flags.add_flags([flag1, flag2, flag3])

print(f"Total flags: {len(flags.flags)}")
for flag in flags:
    print(f"  - {flag.string_entity}: {flag.input_value}")

---

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

Обработка всех флагов с проверкой статусов

Пример использования:

from argenta import Command, Response, Router
from argenta.command import Flag, Flags, InputFlag
from argenta.command.flag import ValidationStatus

router = Router(title="Comprehensive Example")


@router.command(
    Command(
        "validate",
        description="Validate all flags",
        flags=Flags(
            [
                Flag("format", possible_values=["json", "xml"]),
                Flag("output"),
                Flag("force"),
            ]
        ),
    )
)
def validate_handler(response: Response):
    input_flags = response.input_flags

    print("Flag validation results:")

    valid_flags: list[InputFlag] = []
    invalid_flags: list[InputFlag] = []
    undefined_flags: list[InputFlag] = []

    for flag in input_flags:
        if flag.status == ValidationStatus.VALID:
            valid_flags.append(flag)
            print(f"  ✓ {flag.string_entity}: {flag.input_value} (VALID)")
        elif flag.status == ValidationStatus.INVALID:
            invalid_flags.append(flag)
            print(f"  ✗ {flag.string_entity}: {flag.input_value} (INVALID)")
        elif flag.status == ValidationStatus.UNDEFINED:
            undefined_flags.append(flag)
            print(f"  ? {flag.string_entity}: {flag.input_value} (UNDEFINED)")

    print("\nSummary:")
    print(f"  Valid flags: {len(valid_flags)}")
    print(f"  Invalid flags: {len(invalid_flags)}")
    print(f"  Undefined flags: {len(undefined_flags)}")

    if valid_flags:
        print("\nProcessing valid flags:")
        for flag in valid_flags:
            print(f"  Processing {flag.name} = {flag.input_value}")