kolo/Argenta
1
0
Fork 0
mirror of https://github.com/koloideal/Argenta.git synced 2026-06-10 10:05:28 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
5bcae8fe68b5bf1c15f9568e9111103799bfccec
Argenta/README.md
T
kolo 5bcae8fe68 Update README.md
2025-04-24 17:40:53 +03:00

26 KiB
Raw Blame History

Argenta

Python library for creating TUI

Contents

preview
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 = '[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

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

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

.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

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

.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

input_command_handler

def input_command_handler(input_command: InputCommand) -> None

Private. One handler for all input commands

Arguments:

  • input_command: input command as InputCommand

Returns:

None

set_command_register_ignore

def set_command_register_ignore(_: bool) -> None

Private. Sets the router behavior on the input commands register

Arguments:

  • _: is command register ignore

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

Reference in New Issue View Git Blame Copy Permalink