Argenta

Python library for creating TUI

---

Contents

• Installing
• Quick Start
• Documentation
  • App Objects
    • set_description_message_pattern
    • set_invalid_input_flags_handler
    • set_repeated_input_flags_handler
    • set_unknown_command_handler
    • set_empty_command_handler
    • set_exit_command_handler
    • run_polling
    • include_router
    • include_routers
    • add_message_on_startup
  • AutoCompleter Objects
  • PredefinedMessages Objects
  • StaticDividingLine Objects
    • get_full_static_line
  • DynamicDividingLine Objects
    • get_full_dynamic_line
  • NoRegisteredHandlersException Objects
  • UnprocessedInputFlagException Objects
  • RepeatedInputFlagsException Objects
  • EmptyInputCommandException Objects
  • PredefinedFlags Objects
  • InputFlag Objects
    • get_value
  • Flag Objects
  • Flags Objects
    • get_flags
    • add_flag
    • add_flags
    • get_flag
  • InputFlags Objects
    • get_flags
    • add_flag
    • add_flags
    • get_flag
  • Command Objects
  • PositionalArgument Objects
  • OptionalArgument Objects
  • BooleanArgument Objects
  • ArgParse Objects
    • set_args
  • Orchestrator Objects
    • start_polling
    • get_input_args
  • Router Objects
    • @command
    • set_invalid_input_flag_handler
    • input_command_handler
    • set_command_register_ignore
    • get_triggers
    • get_aliases
    • get_title
    • set_title
  • RepeatedFlagNameException Objects
  • TooManyTransferredArgsException Objects
  • RequiredArgumentNotPassedException Objects
  • IncorrectNumberOfHandlerArgsException Objects
  • TriggerContainSpacesException Objects
• Tests

---

An example of the TUI appearance

---

Installing

pip install argenta

or

poetry add argenta

---

Quick start

Example of the simplest TUI with a single command

# routers.py
from argenta.router import Router
from argenta.command import Command


router = Router()

@router.command(Command("hello"))
def handler():
  print("Hello, world!")

# main.py
from argenta.app import App
from argenta.orchestrator import Orchestrator
from routers import router

app: App = App()
orchestrator: Orchestrator = Orchestrator()


def main() -> None:
    app.include_router(router)
    orchestrator.start_polling(app)


if __name__ == '__main__':
    main()

Example TUI with a command that has processed flags

# routers.py
import re
from argenta.router import Router
from argenta.command import Command
from argenta.orchestrator import Orchestrator
from argenta.command.flag.defaults import PredefinedFlags
from argenta.command.flag import Flags, Flag, InputFlags

router = Router()

registered_flags = Flags(PredefinedFlags.HOST,
                         Flag('port', '--', re.compile(r'^[0-9]{1,4}$')))


@router.command(Command("hello"))
def handler():
    print("Hello, world!")


@router.command(Command(trigger="ssh",
                        description='connect via ssh',
                        flags=registered_flags))
def handler_with_flags(flags: InputFlags):
    for flag in flags:
        print(f'Flag name: {flag.get_name()}\n'
              f'Flag value: {flag.get_value()}')

---

Documentation

.app

App Objects

class App(BaseApp)

__init__

def __init__(prompt: str = 'What do you want to do?',
             initial_message: str = 'Argenta',
             farewell_message: str = 'See you',
             exit_command: Command = Command('Q', 'Exit command'),
             system_router_title: str | None = 'System points:',
             ignore_command_register: bool = True,
             dividing_line: StaticDividingLine | DynamicDividingLine = StaticDividingLine(),
             repeat_command_groups: bool = True,
             override_system_messages: bool = False,
             autocompleter: AutoCompleter = AutoCompleter(),
             print_func: Callable[[str], None] = Console().print) -> None

Public. The essence of the application itself.

Configures and manages all aspects of the behavior and presentation of the user interacting with the user

Arguments:

• prompt: displayed before entering the command
• initial_message: displayed at the start of the app
• farewell_message: displayed at the end of the app
• exit_command: the entity of the command that will be terminated when entered
• system_router_title: system router title
• ignore_command_register: whether to ignore the case of the entered commands
• dividing_line: the entity of the dividing line
• repeat_command_groups: whether to repeat the available commands and their description
• override_system_messages: whether to redefine the default formatting of system messages
• autocompleter: the entity of the autocompleter
• print_func: system messages text output function

Returns:

None

---

set_description_message_pattern

def set_description_message_pattern(pattern: Callable[[str, str], str]) -> None

Public. Sets the output pattern of the available commands

Arguments:

• pattern: output pattern of the available commands

Returns:

None

---

set_invalid_input_flags_handler

def set_invalid_input_flags_handler(handler: Callable[[str], None]) -> None

Public. Sets the handler for incorrect flags when entering a command

Arguments:

• handler: handler for incorrect flags when entering a command

Returns:

None

---

set_repeated_input_flags_handler

def set_repeated_input_flags_handler(handler: Callable[[str], None]) -> None

Public. Sets the handler for repeated flags when entering a command

Arguments:

• handler: handler for repeated flags when entering a command

Returns:

None

---

set_unknown_command_handler

def set_unknown_command_handler(handler: Callable[[str], None]) -> None

Public. Sets the handler for unknown commands when entering a command

Arguments:

• handler: handler for unknown commands when entering a command

Returns:

None

---

set_empty_command_handler

def set_empty_command_handler(handler: Callable[[], None]) -> None

Public. Sets the handler for empty commands when entering a command

Arguments:

• handler: handler for empty commands when entering a command

Returns:

None

---

set_exit_command_handler

def set_exit_command_handler(handler: Callable[[], None]) -> None

Public. Sets the handler for exit command when entering a command

Arguments:

• handler: handler for exit command when entering a command

Returns:

None

---

include_router

def include_router(router: Router) -> None

Public. Registers the router in the application

Arguments:

• router: registered router

Returns:

None

---

include_routers

def include_routers(*routers: Router) -> None

Public. Registers the routers in the application

Arguments:

• routers: registered routers

Returns:

None

---

add_message_on_startup

def add_message_on_startup(message: str) -> None

Public. Adds a message that will be displayed when the application is launched

Arguments:

• message: the message being added

Returns:

None

---

.app.autocompleter

AutoCompleter Objects

class AutoCompleter()

__init__

def __init__(history_filename: str = False,
             autocomplete_button: str = 'tab') -> None

Public. Configures and implements auto-completion of input command

Arguments:

• history_filename: the name of the file for saving the history of the autocompleter
• autocomplete_button: the button for auto-completion

Returns:

None

---

.app.defaults

PredefinedMessages Objects

@dataclass
class PredefinedMessages()

Public. A dataclass with predetermined messages for quick use

---

.app.dividing_line

StaticDividingLine Objects

class StaticDividingLine(BaseDividingLine)

__init__

def __init__(unit_part: str = '-', length: int = 25) -> None

Public. The static dividing line

Arguments:

• unit_part: the single part of the dividing line
• length: the length of the dividing line

Returns:

None

---

DynamicDividingLine Objects

class DynamicDividingLine(BaseDividingLine)

__init__

def __init__(unit_part: str = '-') -> None

Public. The dynamic dividing line

Arguments:

• unit_part: the single part of the dividing line

Returns:

None

---

.app.exceptions

NoRegisteredHandlersException Objects

class NoRegisteredHandlersException(Exception)

The router has no registered handlers

---

.command.exceptions

UnprocessedInputFlagException Objects

class UnprocessedInputFlagException(BaseInputCommandException)

Private. Raised when an unprocessed input flag is detected

---

RepeatedInputFlagsException Objects

class RepeatedInputFlagsException(BaseInputCommandException)

Private. Raised when repeated input flags are detected

---

EmptyInputCommandException Objects

class EmptyInputCommandException(BaseInputCommandException)

Private. Raised when an empty input command is detected

---

.command.flag.defaults

PredefinedFlags Objects

@dataclass
class PredefinedFlags()

Public. A dataclass with predefined flags and most frequently used flags for quick use

---

.command.flag

InputFlag Objects

class InputFlag(BaseFlag)

__init__

def __init__(name: str,
             prefix: Literal['-', '--', '---'] = '--',
             value: str = None)

Public. The entity of the flag of the entered command

Arguments:

• name: the name of the input flag
• prefix: the prefix of the input flag
• value: the value of the input flag

Returns:

None

---

get_value

def get_value() -> str | None

Public. Returns the value of the flag

Returns:

the value of the flag as str

---

Flag Objects

class Flag(BaseFlag)

__init__

def __init__(name: str,
             prefix: Literal['-', '--', '---'] = '--',
             possible_values: list[str] | Pattern[str] | False = True) -> None

Public. The entity of the flag being registered for subsequent processing

Arguments:

• name: The name of the flag
• prefix: The prefix of the flag
• possible_values: The possible values of the flag, if False then the flag cannot have a value

Returns:

None

---

Flags Objects

class Flags(BaseFlags)

__init__

def __init__(*flags: Flag)

Public. A model that combines the registered flags

Arguments:

• flags: the flags that will be registered

Returns:

None

---

get_flags

def get_flags() -> list[Flag]

Public. Returns a list of flags

Returns:

list of flags as list[Flag]

---

add_flag

def add_flag(flag: Flag) -> None

Public. Adds a flag to the list of flags

Arguments:

• flag: flag to add

Returns:

None

---

add_flags

def add_flags(flags: list[Flag]) -> None

Public. Adds a list of flags to the list of flags

Arguments:

• flags: list of flags to add

Returns:

None

---

get_flag

def get_flag(name: str) -> Flag | None

Public. Returns the flag entity by its name or None if not found

Arguments:

• name: the name of the flag to get

Returns:

entity of the flag or None

---

InputFlags Objects

class InputFlags(BaseFlags)

__init__

def __init__(*flags: InputFlag)

Public. A model that combines the input flags of the input command

Arguments:

• flags: all input flags

Returns:

None

---

get_flags

def get_flags() -> list[InputFlag]

Public. Returns a list of flags

Returns:

list of flags

---

add_flag

def add_flag(flag: InputFlag) -> None

Public. Adds a flag to the list of flags

Arguments:

• flag: flag to add

Returns:

None

---

add_flags

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

Public. Adds a list of flags to the list of flags

Arguments:

• flags: list of flags to add

Returns:

None

---

get_flag

def get_flag(name: str) -> InputFlag

Public. Returns the flag entity by its name or None if not found

Arguments:

• name: the name of the flag to get

Returns:

entity of the flag or None

---

.command.models

Command Objects

class Command(BaseCommand)

__init__

def __init__(trigger: str,
             description: str = None,
             flags: Flag | Flags = None,
             aliases: list[str] = None)

Public. The command that can and should be registered in the Router

Arguments:

• trigger: A string trigger, which, when entered by the user, indicates that the input corresponds to the command
• description: the description of the command
• flags: processed commands
• aliases: string synonyms for the main trigger

---

.orchestrator.argparse.arguments

PositionalArgument Objects

class PositionalArgument(BaseArgument)

__init__

def __init__(name: str)

Public. Required argument at startup

Arguments:

• name: name of the argument, must not start with minus (-)

---

OptionalArgument Objects

class OptionalArgument(BaseArgument)

__init__

def __init__(name: str, prefix: Literal['-', '--', '---'] = '--')

Public. Optional argument, must have the value

Arguments:

• name: name of the argument
• prefix: prefix of the argument

---

BooleanArgument Objects

class BooleanArgument(BaseArgument)

__init__

def __init__(name: str,
             prefix: Literal['-', '--', '---'] = '--')

Public. Boolean argument, does not require a value

Arguments:

• name: name of the argument
• prefix: prefix of the argument

---

.orchestrator.argparser

ArgParse Objects

class ArgParse()

__init__

def __init__(processed_args: list[PositionalArgument | OptionalArgument | BooleanArgument],
             name: str = 'Argenta',
             description: str = 'Argenta available arguments',
             epilog: str = 'github.com/koloideal/Argenta | made by kolo') -> None

Public. Cmd argument parser and configurator at startup

Arguments:

• name: the name of the ArgParse instance
• description: the description of the ArgParse instance
• epilog: the epilog of the ArgParse instance
• processed_args: registered and processed arguments

---

set_args

def set_args(*args: PositionalArgument | OptionalArgument | BooleanArgument) -> None

Public. Sets the arguments to be processed

Arguments:

• args: processed arguments

Returns:

None

---

.orchestrator

Orchestrator Objects

class Orchestrator()

__init__

def __init__(arg_parser: ArgParse = False)

Public. An orchestrator and configurator that defines the behavior of an integrated system, one level higher than the App

Arguments:

• arg_parser: Cmd argument parser and configurator at startup

Returns:

None

---

start_polling

@staticmethod
def start_polling(app: App) -> None

Public. Starting the user input processing cycle

Arguments:

• app: a running application

Returns:

None

---

get_input_args

def get_input_args() -> Namespace | None

Public. Returns the arguments parsed

Returns:

None

---

.router

Router Objects

class Router()

__init__

def __init__(title: str = None)

Public. Directly configures and manages handlers

Arguments:

• title: the title of the router, displayed when displaying the available commands

Returns:

None

---

@command

def command(command: Command) -> Callable

Public. Registers handler

Arguments:

• command: Registered command

Returns:

decorated handler as Callable[[Any], Any]

---

set_invalid_input_flag_handler

def set_invalid_input_flag_handler(func) -> None

Public. Registers handler for invalid input flag

Arguments:

• func: registered handler

Returns:

None

---

get_triggers

def get_triggers() -> list[str]

Public. Gets registered triggers

Returns:

registered in router triggers as list[str]

---

get_aliases

def get_aliases() -> list[str]

Public. Gets registered aliases

Returns:

registered in router aliases as list[str]

---

get_title

def get_title() -> str | None

Public. Gets title of the router

Returns:

the title of the router as str or None

---

set_title

def set_title(title: str) -> None

Public. Sets the title of the router

Arguments:

• title: title that will be setted

Returns:

None

---

.router.exceptions

RepeatedFlagNameException Objects

class RepeatedFlagNameException(Exception)

Private. Raised when a repeated flag name is registered

---

TooManyTransferredArgsException Objects

class TooManyTransferredArgsException(Exception)

Private. Raised when too many arguments are passed

---

RequiredArgumentNotPassedException Objects

class RequiredArgumentNotPassedException(Exception)

Private. Raised when a required argument is not passed

---

IncorrectNumberOfHandlerArgsException Objects

class IncorrectNumberOfHandlerArgsException(Exception)

Private. Raised when incorrect number of arguments are passed

---

TriggerContainSpacesException Objects

class TriggerContainSpacesException(Exception)

Private. Raised when there is a space in the trigger being registered

---

Tests

Run tests:

python -m unittest discover

or

python -m unittest discover -v

---

made by kolo MIT 2025