diff --git a/Makefile b/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/README2.md b/README2.md new file mode 100644 index 0000000..69fd968 --- /dev/null +++ b/README2.md @@ -0,0 +1,1317 @@ +# Argenta + +Python library for creating TUI + +![preview](https://github.com/koloideal/Argenta/blob/kolo/imgs/mock_app_preview_last.png?raw=True) +Пример внешнего вида 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 + diff --git a/make.bat b/make.bat deleted file mode 100644 index dc1312a..0000000 --- a/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/pyproject.toml b/pyproject.toml index e7b0dd6..1ed90b5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ authors = [ ] license = {text = "MIT"} readme = "README.md" -requires-python = ">=3.11" +requires-python = ">=3.11, <4.0" dependencies = ["rich (>=14.0.0,<15.0.0)", "art (>=6.4,<7.0)", "pyreadline3 (>=3.5.4,<4.0.0)"] @@ -28,4 +28,5 @@ build-backend = "poetry.core.masonry.api" [tool.poetry.group.dev.dependencies] sphinx = "^8.2.3" +pydoc-markdown = "^4.8.2" diff --git a/source/conf.py b/source/conf.py deleted file mode 100644 index 56d5e8f..0000000 --- a/source/conf.py +++ /dev/null @@ -1,27 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = 'Argenta' -copyright = '2025, kolo' -author = 'kolo' - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = ['sphinx.ext.autodoc'] - -templates_path = ['_templates'] -exclude_patterns = [] - - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = 'alabaster' -html_static_path = ['_static'] diff --git a/source/index.rst b/source/index.rst deleted file mode 100644 index 0617667..0000000 --- a/source/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. Argenta documentation master file, created by - sphinx-quickstart on Tue Apr 15 01:13:28 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Argenta documentation -===================== - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - -.. automodule:: argenta \ No newline at end of file