# Argenta
Python library for creating TUI
Пример внешнего вида TUI, написанного с помощью Argenta
---
# Installing
```bash
pip install argenta
```
or
```bash
poetry add argenta
```
---
# Quick start
Example of the simplest TUI with a single command
```python
# routers.py
from argenta.router import Router
from argenta.command import Command
router = Router()
@router.command(Command("hello"))
def handler():
print("Hello, world!")
```
```python
# 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()
```
Пример оболочки с командой, у которой зарегистрированы флаги
```python
# 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
```python
class AutoCompleter()
```
---
#### \_\_init\_\_
```python
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
```python
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
```python
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
```python
def exit_setup() -> None
```
Public. Exit setup function
**Returns**:
None
#### get\_history\_items
```python
@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
```python
@dataclass
class PredefinedMessages()
```
Public. A dataclass with predetermined messages for quick use
# argenta.app.dividing\_line.models
## BaseDividingLine Objects
```python
class BaseDividingLine(ABC)
```
#### \_\_init\_\_
```python
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
```python
def get_unit_part() -> str
```
Private. Returns the unit part of the dividing line
**Returns**:
unit_part of dividing line as str
## StaticDividingLine Objects
```python
class StaticDividingLine(BaseDividingLine)
```
#### \_\_init\_\_
```python
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
```python
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
```python
class DynamicDividingLine(BaseDividingLine)
```
#### \_\_init\_\_
```python
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
```python
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
```python
class NoRegisteredHandlersException(Exception)
```
The router has no registered handlers
# argenta.app.models
## BaseApp Objects
```python
class BaseApp()
```
#### set\_description\_message\_pattern
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
class App(BaseApp)
```
#### \_\_init\_\_
```python
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
```python
def run_polling() -> None
```
Private. Starts the user input processing cycle
**Returns**:
None
#### include\_router
```python
def include_router(router: Router) -> None
```
Public. Registers the router in the application
**Arguments**:
- `router`: registered router
**Returns**:
None
#### include\_routers
```python
def include_routers(*routers: Router) -> None
```
Public. Registers the routers in the application
**Arguments**:
- `routers`: registered routers
**Returns**:
None
#### add\_message\_on\_startup
```python
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
```python
class RegisteredRouters()
```
#### \_\_init\_\_
```python
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
```python
def get_registered_routers() -> list[Router]
```
Private. Returns the registered routers
**Returns**:
registered routers as list[Router]
#### add\_registered\_router
```python
def add_registered_router(router: Router) -> None
```
Private. Adds a new registered router
**Arguments**:
- `router`: registered router
**Returns**:
None
#### add\_registered\_routers
```python
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
```python
class BaseInputCommandException(Exception)
```
Private. Base exception class for all exceptions raised when parse input command
## UnprocessedInputFlagException Objects
```python
class UnprocessedInputFlagException(BaseInputCommandException)
```
Private. Raised when an unprocessed input flag is detected
## RepeatedInputFlagsException Objects
```python
class RepeatedInputFlagsException(BaseInputCommandException)
```
Private. Raised when repeated input flags are detected
## EmptyInputCommandException Objects
```python
class EmptyInputCommandException(BaseInputCommandException)
```
Private. Raised when an empty input command is detected
# argenta.command.flag.defaults
## PredefinedFlags Objects
```python
@dataclass
class PredefinedFlags()
```
Public. A dataclass with predefined flags and most frequently used flags for quick use
# argenta.command.flag.models
## BaseFlag Objects
```python
class BaseFlag(ABC)
```
#### \_\_init\_\_
```python
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
```python
def get_string_entity() -> str
```
Public. Returns a string representation of the flag
**Returns**:
string representation of the flag as str
#### get\_name
```python
def get_name() -> str
```
Public. Returns the name of the flag
**Returns**:
the name of the flag as str
#### get\_prefix
```python
def get_prefix() -> str
```
Public. Returns the prefix of the flag
**Returns**:
the prefix of the flag as str
## InputFlag Objects
```python
class InputFlag(BaseFlag)
```
#### \_\_init\_\_
```python
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
```python
def get_value() -> str | None
```
Public. Returns the value of the flag
**Returns**:
the value of the flag as str
#### set\_value
```python
def set_value(value)
```
Private. Sets the value of the flag
**Arguments**:
- `value`: the fag value to set
**Returns**:
None
## Flag Objects
```python
class Flag(BaseFlag)
```
#### \_\_init\_\_
```python
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
```python
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
```python
class BaseFlags(ABC)
```
Private. Base class for groups of flags
#### get\_flags
```python
@abstractmethod
def get_flags()
```
Public. Returns a list of flags
**Returns**:
list of flags
#### add\_flag
```python
@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
```python
@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
```python
@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
```python
class BaseCommand()
```
#### \_\_init\_\_
```python
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
```python
def get_trigger() -> str
```
Returns the trigger of the command
**Returns**:
the trigger of the command as str
## Command Objects
```python
class Command(BaseCommand)
```
#### \_\_init\_\_
```python
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
```python
class BaseArgument(ABC)
```
#### get\_string\_entity
```python
@abstractmethod
def get_string_entity()
```
Returns the string representation of the argument
## PositionalArgument Objects
```python
class PositionalArgument(BaseArgument)
```
#### \_\_init\_\_
```python
def __init__(name: str)
```
Required argument at startup
**Arguments**:
- `name`: name of the argument, must not start with minus (-)
## OptionalArgument Objects
```python
class OptionalArgument(BaseArgument)
```
#### \_\_init\_\_
```python
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
```python
class BooleanArgument(BaseArgument)
```
#### \_\_init\_\_
```python
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
```python
class ArgParse()
```
#### \_\_init\_\_
```python
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
```python
def set_args(*args: PositionalArgument | OptionalArgument | BooleanArgument)
```
Sets the arguments to be processed
**Arguments**:
- `args`: processed arguments
#### register\_args
```python
def register_args()
```
Registers initialized command line arguments
# argenta.orchestrator.argparse
# argenta.orchestrator.entity
## Orchestrator Objects
```python
class Orchestrator()
```
#### \_\_init\_\_
```python
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
```python
@staticmethod
def start_polling(app: App) -> None
```
Starting the user input processing cycle
**Arguments**:
- `app`: a running application
#### get\_input\_args
```python
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