Command¶

Command is the basic unit of functionality in an application. Each command links a handler to a trigger, which when entered will invoke it for processing.

Command encapsulates all information about a command: its trigger (keyword for invocation), description, set of flags, and set of aliases.

Initialization¶

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

Creates a new command for registration in a router.

trigger: String trigger that the user enters to invoke the command. Serves as the primary identifier.
description: Optional description explaining the command’s purpose. Displayed in help.
flags: Set of flags for configuring behavior. Can be a single Flag object or a Flags collection.
aliases: Set of string aliases for the main trigger.

Attributes:

trigger¶: The main command trigger. Used for its identification when processing user input.

description¶: Text description of the command. If not provided, the default value is used.

registered_flags¶: A Flags object containing all registered flags. If a Flag was passed, it is automatically converted from a single flag to a collection during initialization.

aliases¶: Set of string aliases. Empty if no aliases are defined.

Usage example:

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"],
)

Command Registration¶

Commands are passed as an argument to the @router.command() decorator.

Basic example:

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...")

Commands with flags:

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")

Working with Aliases¶

Aliases allow invoking the same handler with different triggers while preserving the command’s flags and description.

Example with aliases:

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...")

Now the user can invoke the command in any of the following ways:

shutdown
poweroff
halt
stop

All these variants will invoke the same handler handle_shutdown.

InputCommand¶

InputCommand represents a processed command entered by the user. This internal class is created automatically when processing user input. Direct work with it is possible when creating a custom handler for unknown commands.