Command

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

Command инкапсулирует всю информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов и множество псевдонимов.

---

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

__init__(self, trigger: str, *,
         description: str | None = None,
         flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
         aliases: set[str] = DEFAULT_WITHOUT_ALIASES) -> None

Создаёт новую команду для регистрации в роутере.

• trigger: Строковый триггер, который пользователь вводит для вызова команды. Является основным идентификатором.

• description: Необязательное описание, объясняющее назначение команды. Отображается в справке.

• flags: Набор флагов для настройки поведения. Может быть одиночным объектом Flag или коллекцией Flags.

• aliases: Множество строковых псевдонимов для основного триггера.

Атрибуты:

trigger

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

description

Текстовое описание команды. Если не передано, используется значение по умолчанию.

registered_flags

Объект Flags, содержащий все зарегистрированные флаги. Если был передан Flag, то автоматически конвертируется из одиночного в коллекцию при инициализации.

aliases

Множество строковых псевдонимов. Пуст, если псевдонимы не заданы.

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

from argenta.command import Flag, Flags, Command

# Simple command without flags
hello_cmd = Command("hello", description="Greet the user")

# Command with description and aliases
quit_cmd = Command("quit", description="Exit the application", aliases=["exit", "q"])

# Command with flags
deploy_cmd = Command(
    "deploy",
    description="Deploy application to server",
    flags=Flags(
        [
            Flag("env", possible_values=["dev", "prod"]),
            Flag("force"),
        ]
    ),
    aliases=["dep"],
)

См. также

Подробнее про флаги: Flags и Флаги команд.

---

Регистрация команд

Команды передаются в качестве аргумента в декоратор @router.command().

Базовый пример:

from argenta import Command, Response, Router

router = Router(title="User Management")


@router.command(Command("create-user", description="Create a new user account"))
def handle_create_user(response: Response):
    print("Creating new user...")


@router.command(
    Command(
        "delete-user",
        description="Delete existing user account",
        aliases=["remove-user", "rm-user"],
    )
)
def handle_delete_user(response: Response):
    print("Deleting user...")

Команды с флагами:

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

router = Router(title="Server Management")


@router.command(
    Command(
        "start",
        description="Start the server",
        flags=Flags(
            [
                Flag("port"),
                Flag("host"),
                Flag("debug"),
            ]
        ),
        aliases=["run"],
    )
)
def handle_start(response: Response):
    input_flags = response.input_flags
    port_flag = input_flags.get_flag_by_name("port")
    host_flag = input_flags.get_flag_by_name("host")
    debug_flag = input_flags.get_flag_by_name("debug")

    host = host_flag.input_value if host_flag else "localhost"
    port = port_flag.input_value if port_flag else "8080"
    debug = debug_flag and debug_flag.input_value

    print(f"Starting server on {host}:{port}")
    if debug:
        print("Debug mode: ON")

---

Работа с псевдонимами

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

Пример с псевдонимами:

from argenta import Router, Command, Response

router = Router(title="System")


@router.command(
    Command(
        "shutdown",
        description="Shutdown the system",
        aliases=["poweroff", "halt", "stop"]
    )
)
def handle_shutdown(response: Response):
    print("Shutting down the system...")

Теперь пользователь может вызвать команду любым из способов:

shutdown
poweroff
halt
stop

Все эти варианты вызовут один и тот же хэндлер handle_shutdown.

---

InputCommand

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

См. также

Подробнее о пользовательских обработчиках исключений см. здесь.

Атрибуты:

trigger

Строковый триггер, введённый пользователем.

input_flags

Объект InputFlags, содержащий все введённые и распаршенные флаги.