argenta 0.5.0b0__py3-none-any.whl → 1.0.0__py3-none-any.whl

argenta/orchestrator/argparser/__init__.py

@@ -0,0 +1,4 @@
+__all__ = ["ArgParser"]
+
+
+from argenta.orchestrator.argparser.entity import ArgParser

argenta/orchestrator/argparser/arguments/__init__.py

@@ -0,0 +1,8 @@
+__all__ = ["BooleanArgument", "PositionalArgument", "OptionalArgument"]
+
+
+from argenta.orchestrator.argparser.arguments.models import (
+    BooleanArgument,
+    PositionalArgument,
+    OptionalArgument,
+)

argenta/orchestrator/argparser/arguments/models.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+from typing import Literal
+
+
+class BaseArgument(ABC):
+    """
+    Private. Base class for all arguments
+    """
+
+    @abstractmethod
+    def get_string_entity(self) -> str:
+        """
+        Public. Returns the string representation of the argument
+        :return: the string representation as a str
+        """
+        pass
+
+
+class PositionalArgument(BaseArgument):
+    def __init__(self, name: str):
+        """
+        Public. Required argument at startup
+        :param name: name of the argument, must not start with minus (-)
+        """
+        self.name = name
+
+    def get_string_entity(self):
+        return self.name
+
+
+class OptionalArgument(BaseArgument):
+    def __init__(self, name: str, prefix: Literal["-", "--", "---"] = "--"):
+        """
+        Public. Optional argument, must have the value
+        :param name: name of the argument
+        :param prefix: prefix of the argument
+        """
+        self.name = name
+        self.prefix = prefix
+
+    def get_string_entity(self):
+        return self.prefix + self.name
+
+
+class BooleanArgument(BaseArgument):
+    def __init__(self, name: str, prefix: Literal["-", "--", "---"] = "--"):
+        """
+        Public. Boolean argument, does not require a value
+        :param name: name of the argument
+        :param prefix: prefix of the argument
+        """
+        self.name = name
+        self.prefix = prefix
+
+    def get_string_entity(self):
+        return self.prefix + self.name

argenta/orchestrator/argparser/entity.py

@@ -0,0 +1,59 @@
+from argparse import ArgumentParser
+
+from argenta.orchestrator.argparser.arguments.models import (
+    BooleanArgument,
+    OptionalArgument,
+    PositionalArgument,
+)
+
+
+class ArgParser:
+    def __init__(
+        self,
+        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
+        :param name: the name of the ArgParse instance
+        :param description: the description of the ArgParse instance
+        :param epilog: the epilog of the ArgParse instance
+        :param processed_args: registered and processed arguments
+        """
+        self.name = name
+        self.description = description
+        self.epilog = epilog
+
+        self.entity: ArgumentParser = ArgumentParser(
+            prog=name, description=description, epilog=epilog
+        )
+        self.args: (
+            list[PositionalArgument | OptionalArgument | BooleanArgument] | None
+        ) = processed_args
+
+    def set_args(
+        self, *args: PositionalArgument | OptionalArgument | BooleanArgument
+    ) -> None:
+        """
+        Public. Sets the arguments to be processed
+        :param args: processed arguments
+        :return: None
+        """
+        self.args.extend(args)
+
+    def register_args(self) -> None:
+        """
+        Private. Registers initialized command line arguments
+        :return: None
+        """
+        if not self.args:
+            return
+        for arg in self.args:
+            if type(arg) is PositionalArgument:
+                self.entity.add_argument(arg.get_string_entity())
+            elif type(arg) is OptionalArgument:
+                self.entity.add_argument(arg.get_string_entity())
+            elif type(arg) is BooleanArgument:
+                self.entity.add_argument(arg.get_string_entity(), action="store_true")

argenta/orchestrator/entity.py

@@ -0,0 +1,35 @@
+from argparse import Namespace
+
+from argenta.app import App
+from argenta.orchestrator.argparser import ArgParser
+
+
+class Orchestrator:
+    def __init__(self, arg_parser: ArgParser = False):
+        """
+        Public. An orchestrator and configurator that defines the behavior of an integrated system, one level higher than the App
+        :param arg_parser: Cmd argument parser and configurator at startup
+        :return: None
+        """
+        self.arg_parser: ArgParser | False = arg_parser
+        if arg_parser:
+            self.arg_parser.register_args()
+
+    @staticmethod
+    def start_polling(app: App) -> None:
+        """
+        Public. Starting the user input processing cycle
+        :param app: a running application
+        :return: None
+        """
+        app.run_polling()
+
+    def get_input_args(self) -> Namespace | None:
+        """
+        Public. Returns the arguments parsed
+        :return: None
+        """
+        if self.arg_parser:
+            return self.arg_parser.entity.parse_args()
+        else:
+            return None

argenta/response/__init__.py

@@ -0,0 +1,5 @@
+__all__ = ["Response", "Status"]
+
+
+from argenta.response.entity import Response
+from argenta.response.status import Status

argenta/response/entity.py

@@ -0,0 +1,29 @@
+from argenta.response.status import Status
+from argenta.command.flags import (
+    ValidInputFlags,
+    UndefinedInputFlags,
+    InvalidValueInputFlags,
+)
+
+
+class Response:
+    __slots__ = ("status", "valid_flags", "undefined_flags", "invalid_value_flags")
+
+    def __init__(
+        self,
+        status: Status = None,
+        valid_flags: ValidInputFlags = ValidInputFlags(),
+        undefined_flags: UndefinedInputFlags = UndefinedInputFlags(),
+        invalid_value_flags: InvalidValueInputFlags = InvalidValueInputFlags(),
+    ):
+        """
+        Public. The entity of the user input sent to the handler
+        :param status: the status of the response
+        :param valid_flags: valid input flags
+        :param undefined_flags: undefined input flags
+        :param invalid_value_flags: input flags with invalid values
+        """
+        self.status = status
+        self.valid_flags = valid_flags
+        self.undefined_flags = undefined_flags
+        self.invalid_value_flags = invalid_value_flags

argenta/response/status.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class Status(Enum):
+    ALL_FLAGS_VALID = "ALL_FLAGS_VALID"
+    UNDEFINED_FLAGS = "UNDEFINED_FLAGS"
+    INVALID_VALUE_FLAGS = "INVALID_VALUE_FLAGS"
+    UNDEFINED_AND_INVALID_FLAGS = "UNDEFINED_AND_INVALID_FLAGS"

argenta/router/__init__.py

@@ -1,4 +1,4 @@
 __all__ = ["Router"]
 
 
-from argenta.router.entity import Router
+from argenta.router.entity import Router

argenta/router/command_handler/entity.py

@@ -1,21 +1,67 @@
-from typing import Callable
+from typing import Callable, Iterator
+
 from argenta.command import Command
-from argenta.command.flag.models import InputFlags
+from argenta.response import Response
 
 
 class CommandHandler:
-    def __init__(self, handler: Callable[[], None] | Callable[[InputFlags], None], handled_command: Command):
+    def __init__(self, handler: Callable[[Response], None], handled_command: Command):
+        """
+        Private. Entity of the model linking the handler and the command being processed
+        :param handler: the handler being called
+        :param handled_command: the command being processed
+        """
         self._handler = handler
         self._handled_command = handled_command
 
-    def handling(self, input_flags: InputFlags = None):
-        if input_flags is not None:
-            self._handler(input_flags)
-        else:
-            self._handler()
+    def handling(self, response: Response) -> None:
+        """
+        Private. Direct processing of an input command
+        :param response: the entity of response: various groups of flags and status of response
+        :return: None
+        """
+        self._handler(response)
 
-    def get_handler(self):
+    def get_handler(self) -> Callable[[Response], None]:
+        """
+        Private. Returns the handler being called
+        :return: the handler being called as Callable[[Response], None]
+        """
         return self._handler
 
-    def get_handled_command(self):
-        return self._handled_command
+    def get_handled_command(self) -> Command:
+        """
+        Private. Returns the command being processed
+        :return: the command being processed as Command
+        """
+        return self._handled_command
+
+
+class CommandHandlers:
+    def __init__(self, command_handlers: list[CommandHandler] = None):
+        """
+        Private. The model that unites all CommandHandler of the routers
+        :param command_handlers: list of CommandHandlers for register
+        """
+        self.command_handlers = command_handlers if command_handlers else []
+
+    def get_handlers(self) -> list[CommandHandler]:
+        """
+        Private. Returns the list of CommandHandlers
+        :return: the list of CommandHandlers as list[CommandHandler]
+        """
+        return self.command_handlers
+
+    def add_handler(self, command_handler: CommandHandler) -> None:
+        """
+        Private. Adds a CommandHandler to the list of CommandHandlers
+        :param command_handler: CommandHandler to be added
+        :return: None
+        """
+        self.command_handlers.append(command_handler)
+
+    def __iter__(self) -> Iterator[CommandHandler]:
+        return iter(self.command_handlers)
+
+    def __next__(self) -> CommandHandler:
+        return next(iter(self.command_handlers))

argenta/router/defaults.py

@@ -1,5 +1,4 @@
 from argenta.router import Router
 
 
-system_router = Router(title='System points:',
-                       name='System')
+system_router = Router(title="System points:")

argenta/router/entity.py

@@ -1,149 +1,238 @@
-from typing import Callable, Any
-from inspect import getfullargspec
+from typing import Callable, Literal, Type
+from inspect import getfullargspec, get_annotations, getsourcefile, getsourcelines
+from rich.console import Console
 
 from argenta.command import Command
 from argenta.command.models import InputCommand
-from argenta.router.command_handlers.entity import CommandHandlers
-from argenta.router.command_handler.entity import CommandHandler
-from argenta.command.flag.models import Flag, Flags, InputFlags
-from argenta.router.exceptions import (RepeatedFlagNameException,
-                                       TooManyTransferredArgsException,
-                                       RequiredArgumentNotPassedException,
-                                       IncorrectNumberOfHandlerArgsException,
-                                       TriggerCannotContainSpacesException)
+from argenta.response import Response, Status
+from argenta.router.command_handler.entity import CommandHandlers, CommandHandler
+from argenta.command.flags.models import (
+    Flags,
+    InputFlags,
+    UndefinedInputFlags,
+    ValidInputFlags,
+    InvalidValueInputFlags,
+)
+from argenta.router.exceptions import (
+    RepeatedFlagNameException,
+    TooManyTransferredArgsException,
+    RequiredArgumentNotPassedException,
+    TriggerContainSpacesException,
+)
 
 
 class Router:
-    def __init__(self,
-                 title: str = None,
-                 name: str = 'Default'):
-        self._title = title
-        self._name = name
+    def __init__(self, title: str | None = "Awesome title"):
+        """
+        Public. Directly configures and manages handlers
+        :param title: the title of the router, displayed when displaying the available commands
+        :return: None
+        """
+        self.title = title
 
         self._command_handlers: CommandHandlers = CommandHandlers()
         self._ignore_command_register: bool = False
-        self._not_valid_flag_handler: Callable[[Flag], None] = lambda flag: print(f"Undefined or incorrect input flag: {flag.get_string_entity()}{(' '+flag.get_value()) if flag.get_value() else ''}")
 
-
-    def command(self, command: Command) -> Callable[[Any],  Any]:
+    def command(self, command: Command | str) -> Callable:
+        """
+        Public. Registers handler
+        :param command: Registered command
+        :return: decorated handler as Callable
+        """
         self._validate_command(command)
+        if isinstance(command, str):
+            command = Command(command)
 
         def command_decorator(func):
-            Router._validate_func_args(command, func)
-            self._command_handlers.add_command_handler(CommandHandler(func, command))
+            Router._validate_func_args(func)
+            self._command_handlers.add_handler(CommandHandler(func, command))
 
             def wrapper(*args, **kwargs):
                 return func(*args, **kwargs)
+
             return wrapper
 
         return command_decorator
 
-
-    def set_invalid_input_flag_handler(self, func):
-        processed_args = getfullargspec(func).args
-        if len(processed_args) != 1:
-            raise IncorrectNumberOfHandlerArgsException()
-        else:
-            self._not_valid_flag_handler = func
-
-
-    def input_command_handler(self, input_command: InputCommand):
+    def finds_appropriate_handler(self, input_command: InputCommand) -> None:
+        """
+        Private. Finds the appropriate handler for given input command and passes control to it
+        :param input_command: input command as InputCommand
+        :return: None
+        """
         input_command_name: str = input_command.get_trigger()
         input_command_flags: InputFlags = input_command.get_input_flags()
 
         for command_handler in self._command_handlers:
             handle_command = command_handler.get_handled_command()
             if input_command_name.lower() == handle_command.get_trigger().lower():
-                self._validate_input_command(input_command_flags, command_handler)
-            elif handle_command.get_aliases():
-                if input_command_name.lower() in handle_command.get_aliases():
-                    self._validate_input_command(input_command_flags, command_handler)
-
-
-    def _validate_input_command(self, input_command_flags: InputFlags, command_handler: CommandHandler):
+                self.process_input_command(input_command_flags, command_handler)
+            if input_command_name.lower() in handle_command.get_aliases():
+                self.process_input_command(input_command_flags, command_handler)
+
+    def process_input_command(
+        self, input_command_flags: InputFlags, command_handler: CommandHandler
+    ) -> None:
+        """
+        Private. Processes input command with the appropriate handler
+        :param input_command_flags: input command flags as InputFlags
+        :param command_handler: command handler for input command as CommandHandler
+        :return: None
+        """
         handle_command = command_handler.get_handled_command()
+        response: Response = Response()
         if handle_command.get_registered_flags().get_flags():
             if input_command_flags.get_flags():
-                if self._validate_input_flags(handle_command, input_command_flags):
-                    command_handler.handling(input_command_flags)
-                    return
+                response: Response = self._structuring_input_flags(
+                    handle_command, input_command_flags
+                )
+                command_handler.handling(response)
             else:
-                command_handler.handling(input_command_flags)
-                return
+                response.status = Status.ALL_FLAGS_VALID
+                command_handler.handling(response)
         else:
             if input_command_flags.get_flags():
-                self._not_valid_flag_handler(input_command_flags[0])
-                return
+                response.status = Status.UNDEFINED_FLAGS
+                response.undefined_flags = UndefinedInputFlags()
+                response.undefined_flags.add_flags(input_command_flags.get_flags())
+                command_handler.handling(response)
             else:
-                command_handler.handling()
-                return
-
+                response.status = Status.ALL_FLAGS_VALID
+                command_handler.handling(response)
 
-    def _validate_input_flags(self, handle_command: Command, input_flags: InputFlags):
+    @staticmethod
+    def _structuring_input_flags(
+        handled_command: Command, input_flags: InputFlags
+    ) -> Response:
+        """
+        Private. Validates flags of input command
+        :param handled_command: entity of the handled command
+        :param input_flags:
+        :return: entity of response as Response
+        """
+        valid_input_flags: ValidInputFlags = ValidInputFlags()
+        invalid_value_input_flags: InvalidValueInputFlags = InvalidValueInputFlags()
+        undefined_input_flags: UndefinedInputFlags = UndefinedInputFlags()
         for flag in input_flags:
-            is_valid = handle_command.validate_input_flag(flag)
-            if not is_valid:
-                self._not_valid_flag_handler(flag)
-                return False
-        return True
+            flag_status: Literal["Undefined", "Valid", "Invalid"] = (
+                handled_command.validate_input_flag(flag)
+            )
+            match flag_status:
+                case "Valid":
+                    valid_input_flags.add_flag(flag)
+                case "Undefined":
+                    undefined_input_flags.add_flag(flag)
+                case "Invalid":
+                    invalid_value_input_flags.add_flag(flag)
+
+        if (
+            not invalid_value_input_flags.get_flags()
+            and not undefined_input_flags.get_flags()
+        ):
+            status = Status.ALL_FLAGS_VALID
+        elif (
+            invalid_value_input_flags.get_flags()
+            and not undefined_input_flags.get_flags()
+        ):
+            status = Status.INVALID_VALUE_FLAGS
+        elif (
+            not invalid_value_input_flags.get_flags()
+            and undefined_input_flags.get_flags()
+        ):
+            status = Status.UNDEFINED_FLAGS
+        else:
+            status = Status.UNDEFINED_AND_INVALID_FLAGS
 
+        return Response(
+            invalid_value_flags=invalid_value_input_flags,
+            valid_flags=valid_input_flags,
+            status=status,
+            undefined_flags=undefined_input_flags,
+        )
 
     @staticmethod
-    def _validate_command(command: Command):
-        command_name: str = command.get_trigger()
-        if command_name.find(' ') != -1:
-            raise TriggerCannotContainSpacesException()
-
-        flags: Flags = command.get_registered_flags()
-        if flags:
-            flags_name: list = [x.get_string_entity().lower() for x in flags]
-            if len(set(flags_name)) < len(flags_name):
-                raise RepeatedFlagNameException()
-
+    def _validate_command(command: Command | str) -> None:
+        """
+        Private. Validates the command registered in handler
+        :param command: validated command
+        :return: None if command is valid else raise exception
+        """
+        match type(command).__name__:
+            case "Command":
+                command_name: str = command.get_trigger()
+                if command_name.find(" ") != -1:
+                    raise TriggerContainSpacesException()
+                flags: Flags = command.get_registered_flags()
+                if flags:
+                    flags_name: list = [x.get_string_entity().lower() for x in flags]
+                    if len(set(flags_name)) < len(flags_name):
+                        raise RepeatedFlagNameException()
+            case "str":
+                if command.find(" ") != -1:
+                    raise TriggerContainSpacesException()
 
     @staticmethod
-    def _validate_func_args(command: Command, func: Callable):
-        registered_args = command.get_registered_flags()
+    def _validate_func_args(func: Callable) -> None:
+        """
+        Private. Validates the arguments of the handler
+        :param func: entity of the handler func
+        :return: None if func is valid else raise exception
+        """
         transferred_args = getfullargspec(func).args
-        if registered_args.get_flags() and transferred_args:
-           if len(transferred_args) != 1:
-                raise TooManyTransferredArgsException()
-        elif registered_args.get_flags() and not transferred_args:
-            raise RequiredArgumentNotPassedException()
-        elif not registered_args.get_flags() and transferred_args:
+        if len(transferred_args) > 1:
             raise TooManyTransferredArgsException()
+        elif len(transferred_args) == 0:
+            raise RequiredArgumentNotPassedException()
 
+        transferred_arg: str = transferred_args[0]
+        func_annotations: dict[str, Type] = get_annotations(func)
 
-    def set_ignore_command_register(self, ignore_command_register: bool):
-        self._ignore_command_register = ignore_command_register
-
-
-    def get_triggers(self):
+        if arg_annotation := func_annotations.get(transferred_arg):
+            if arg_annotation is Response:
+                pass
+            else:
+                file_path: str = getsourcefile(func)
+                source_line: int = getsourcelines(func)[1] + 1
+                fprint = Console().print
+                fprint(
+                    f'\nFile "{file_path}", line {source_line}\n[b red]WARNING:[/b red] [i]The typehint '
+                    f"of argument([green]{transferred_arg}[/green]) passed to the handler is [/i][bold blue]{Response}[/bold blue],"
+                    f" [i]but[/i] [bold blue]{arg_annotation}[/bold blue] [i]is specified[/i]\n",
+                    highlight=False,
+                )
+
+    def set_command_register_ignore(self, _: bool) -> None:
+        """
+        Private. Sets the router behavior on the input commands register
+        :param _: is command register ignore
+        :return: None
+        """
+        self._ignore_command_register = _
+
+    def get_triggers(self) -> list[str]:
+        """
+        Public. Gets registered triggers
+        :return: registered in router triggers as list[str]
+        """
         all_triggers: list[str] = []
         for command_handler in self._command_handlers:
             all_triggers.append(command_handler.get_handled_command().get_trigger())
         return all_triggers
 
-
-    def get_aliases(self):
+    def get_aliases(self) -> list[str]:
+        """
+        Public. Gets registered aliases
+        :return: registered in router aliases as list[str]
+        """
         all_aliases: list[str] = []
         for command_handler in self._command_handlers:
             if command_handler.get_handled_command().get_aliases():
                 all_aliases.extend(command_handler.get_handled_command().get_aliases())
         return all_aliases
 
-
     def get_command_handlers(self) -> CommandHandlers:
+        """
+        Private. Gets registered command handlers
+        :return: registered command handlers as CommandHandlers
+        """
         return self._command_handlers
-
-
-    def get_name(self) -> str:
-        return self._name
-
-
-    def get_title(self) -> str | None:
-        return self._title
-
-
-    def set_title(self, title: str):
-        self._title = title