Argenta/README2.md

Argenta

Python library for creating TUI

Пример внешнего вида TUI, написанного с помощью Argenta

---

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

Пример оболочки с командой, у которой зарегистрированы флаги

# 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()}')

---

argenta.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

complete

def complete(text, state) -> str | None

Private. Auto-completion function

Arguments:

• text: part of the command being entered
• state: the current cursor position is relative to the beginning of the line

Returns:

the desired candidate as str or None

initial_setup

def initial_setup(all_commands: list[str]) -> None

Public. Initial setup function

Arguments:

• all_commands: Registered commands for adding them to the autocomplete history

Returns:

None

exit_setup

def exit_setup() -> None

Public. Exit setup function

Returns:

None

get_history_items

@staticmethod
def get_history_items() -> list[str] | list

Private. Returns a list of all commands entered by the user

Returns:

all commands entered by the user as list[str]

argenta.app.defaults

PredefinedMessages Objects

@dataclass
class PredefinedMessages()

Public. A dataclass with predetermined messages for quick use

argenta.app.dividing_line.models

BaseDividingLine Objects

class BaseDividingLine(ABC)

__init__

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

Private. The basic dividing line

Arguments:

• unit_part: the single part of the dividing line

Returns:

None

get_unit_part

def get_unit_part() -> str

Private. Returns the unit part of the dividing line

Returns:

unit_part of dividing line as str

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

get_full_static_line

def get_full_static_line(is_override: bool) -> str

Private. Returns the full line of the dividing line

Arguments:

• is_override: has the default text layout been redefined

Returns:

full line of dividing line as str

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

get_full_dynamic_line

def get_full_dynamic_line(length: int, is_override: bool) -> str

Private. Returns the full line of the dividing line

Arguments:

• length: the length of the dividing line
• is_override: has the default text layout been redefined

Returns:

full line of dividing line as str

argenta.app.dividing_line

argenta.app.exceptions

NoRegisteredHandlersException Objects

class NoRegisteredHandlersException(Exception)

The router has no registered handlers

argenta.app.models

BaseApp Objects

class BaseApp()

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

App Objects

class App(BaseApp)

__init__

def __init__(prompt: str = '[italic dim bold]What do you want to do?\n',
             initial_message: str = '\nArgenta\n',
             farewell_message: str = '\nSee you\n',
             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

run_polling

def run_polling() -> None

Private. Starts the user input processing cycle

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

argenta.app.registered_routers.entity

RegisteredRouters Objects

class RegisteredRouters()

__init__

def __init__(registered_routers: list[Router] = None) -> None

Private. Combines registered routers

Arguments:

• registered_routers: list of the registered routers

Returns:

None

get_registered_routers

def get_registered_routers() -> list[Router]

Private. Returns the registered routers

Returns:

registered routers as list[Router]

add_registered_router

def add_registered_router(router: Router) -> None

Private. Adds a new registered router

Arguments:

• router: registered router

Returns:

None

add_registered_routers

def add_registered_routers(*routers: Router) -> None

Private. Adds new registered routers

Arguments:

• routers: registered routers

Returns:

None

argenta.app.registered_routers

argenta.app

argenta.command.exceptions

BaseInputCommandException Objects

class BaseInputCommandException(Exception)

Private. Base exception class for all exceptions raised when parse input command

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

argenta.command.flag.defaults

PredefinedFlags Objects

@dataclass
class PredefinedFlags()

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

argenta.command.flag.models

BaseFlag Objects

class BaseFlag(ABC)

__init__

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

Private. Base class for flags

Arguments:

• name: the name of the flag
• prefix: the prefix of the flag

Returns:

None

get_string_entity

def get_string_entity() -> str

Public. Returns a string representation of the flag

Returns:

string representation of the flag as str

get_name

def get_name() -> str

Public. Returns the name of the flag

Returns:

the name of the flag as str

get_prefix

def get_prefix() -> str

Public. Returns the prefix of the flag

Returns:

the prefix of the flag as str

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

set_value

def set_value(value)

Private. Sets the value of the flag

Arguments:

• value: the fag value to set

Returns:

None

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

validate_input_flag_value

def validate_input_flag_value(input_flag_value: str | None)

Private. Validates the input flag value

Arguments:

• input_flag_value: The input flag value to validate

Returns:

whether the entered flag is valid as bool

BaseFlags Objects

class BaseFlags(ABC)

Private. Base class for groups of flags

get_flags

@abstractmethod
def get_flags()

Public. Returns a list of flags

Returns:

list of flags

add_flag

@abstractmethod
def add_flag(flag: Flag | InputFlag)

Public. Adds a flag to the list of flags

Arguments:

• flag: flag to add

Returns:

None

add_flags

@abstractmethod
def add_flags(flags: list[Flag] | list[InputFlag])

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

Arguments:

• flags: list of flags to add

Returns:

None

get_flag

@abstractmethod
def get_flag(name: str)

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

argenta.command.flag

argenta.command.models

BaseCommand Objects

class BaseCommand()

__init__

def __init__(trigger: str) -> None

Private. Base class for all commands

Arguments:

• trigger: A string trigger, which, when entered by the user, indicates that the input corresponds to the command

get_trigger

def get_trigger() -> str

Returns the trigger of the command

Returns:

the trigger of the command as str

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

argenta.command

argenta.orchestrator.argparse.arguments.models

BaseArgument Objects

class BaseArgument(ABC)

get_string_entity

@abstractmethod
def get_string_entity()

Returns the string representation of the argument

PositionalArgument Objects

class PositionalArgument(BaseArgument)

__init__

def __init__(name: str)

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['-', '--', '---'] = '--')

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['-', '--', '---'] = '--')

Boolean argument, does not require a value

Arguments:

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

argenta.orchestrator.argparse.arguments

argenta.orchestrator.argparse.entity

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

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)

Sets the arguments to be processed

Arguments:

• args: processed arguments

register_args

def register_args()

Registers initialized command line arguments

argenta.orchestrator.argparse

argenta.orchestrator.entity

Orchestrator Objects

class Orchestrator()

__init__

def __init__(arg_parser: ArgParse = False)

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

start_polling

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

Starting the user input processing cycle

Arguments:

• app: a running application

get_input_args

def get_input_args() -> Namespace | None

Returns the arguments parsed

argenta.orchestrator

argenta.router.command_handler.entity

argenta.router.command_handler

argenta.router.defaults

argenta.router.entity

argenta.router.exceptions

argenta.router