Router

Router is the main building block for organizing logic in an application. Its purpose is to group related commands and their handlers. Each router represents a logical container for a specific set of functions.

For example, in a user management application, one router can handle authentication (login, logout), while another handles profile operations (profile-show, profile-edit).

Initialization

1   __init__(self, title: str | None = None,
2            disable_redirect_stdout: bool = False) -> None

Creates a new router instance.

  • title: Optional title for the command group. Displayed in the list of available commands to help users navigate.

  • disable_redirect_stdout: If True, disables stdout capture for all commands in this router. This is necessary for interactive commands (e.g., with input()). When capture is disabled, a static separator line is automatically used. See Overriding standard output for more details.

Command Registration

The @command decorator is used to register a command and bind a handler to it.

@command(self, command: Command | str)

Decorator for registering a function as a command handler.

Parameters:

command – A Command instance describing the trigger, flags, and command description. Can be a string that will become the trigger (without the ability to configure flags and description).

Usage example:

1from argenta import Command, Response, Router
2
3user_router = Router(title="User Management")
4
5@user_router.command(Command("add-user", description="Adds a new user"))
6def add_user_handler(response: Response):
7    print("User added successfully!")

System Router

Argenta comes with a built-in system router that is automatically connected to every application.

system_router

A predefined Router instance with basic system commands (by default, the exit command). Has the title “System points:”, which can be overridden in App.

You can add your own commands to this router. To do this, use the .system_router attribute of the created Orchestrator instance and use its @command decorator.

Possible Exceptions

The following exceptions may occur when registering commands and flags in Router:

exception TriggerContainSpacesException

Raised if the command trigger in Command contains spaces. Triggers must be a single word.

Incorrect: Command("add user")

Correct: Command("add-user")

exception RepeatedFlagNameException

Raised if duplicate names were used when defining flags for a command. Flag names within a single command must be unique.

Example that raises an exception:

1Command("send", flags=[
2    Flag("recipient"),
3    Flag("recipient")  # Duplicate!
4])
exception RequiredArgumentNotPassedException

Raised if the command handler does not accept the required Response argument.

exception RepeatedTriggerNameException

Raised if duplicate triggers were used when registering commands in the router. Each command must have a unique trigger within a single router.

Example that raises an exception:

1router = Router()
2
3@router.command(Command("start"))
4def start_handler(response: Response) -> None:
5    pass
6
7@router.command(Command("start"))  # Duplicate trigger!
8def another_start_handler(response: Response) -> None:
9    pass
exception RepeatedAliasNameException

Raised if duplicate aliases were used when registering commands. Aliases must be unique within the entire router.

Example that raises an exception:

1router = Router()
2
3@router.command(Command("start", aliases={"s", "run"}))
4def start_handler(response: Response) -> None:
5    pass
6
7@router.command(Command("begin", aliases={"s"}))  # Duplicate alias "s"!
8def begin_handler(response: Response) -> None:
9    pass