argenta 0.5.0b2__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

argenta/app/registered_routers/entity.py

@@ -3,15 +3,34 @@ from argenta.router import Router
 
 class RegisteredRouters:
     def __init__(self, registered_routers: list[Router] = None) -> None:
+        """
+        Private. Combines registered routers
+        :param registered_routers: list of the registered routers
+        :return: None
+        """
         self._registered_routers = registered_routers if registered_routers else []
 
     def get_registered_routers(self) -> list[Router]:
+        """
+        Private. Returns the registered routers
+        :return: registered routers as list[Router]
+        """
         return self._registered_routers
 
-    def add_registered_router(self, router: Router):
+    def add_registered_router(self, router: Router) -> None:
+        """
+        Private. Adds a new registered router
+        :param router: registered router
+        :return: None
+        """
         self._registered_routers.append(router)
 
-    def add_registered_routers(self, *routers: Router):
+    def add_registered_routers(self, *routers: Router) -> None:
+        """
+        Private. Adds new registered routers
+        :param routers: registered routers
+        :return: None
+        """
         self._registered_routers.extend(routers)
 
     def __iter__(self):

argenta/command/exceptions.py

@@ -2,15 +2,24 @@ from argenta.command.flag.models import InputFlag, Flag
 
 
 class BaseInputCommandException(Exception):
+    """
+    Private. Base exception class for all exceptions raised when parse input command
+    """
     pass
 
 
 class UnprocessedInputFlagException(BaseInputCommandException):
+    """
+    Private. Raised when an unprocessed input flag is detected
+    """
     def __str__(self):
         return "Unprocessed Input Flags"
 
 
 class RepeatedInputFlagsException(BaseInputCommandException):
+    """
+    Private. Raised when repeated input flags are detected
+    """
     def __init__(self, flag: Flag | InputFlag):
         self.flag = flag
     def __str__(self):
@@ -19,5 +28,8 @@ class RepeatedInputFlagsException(BaseInputCommandException):
 
 
 class EmptyInputCommandException(BaseInputCommandException):
+    """
+    Private. Raised when an empty input command is detected
+    """
     def __str__(self):
         return "Input Command is empty"

argenta/command/flag/defaults.py

@@ -4,18 +4,21 @@ import re
 
 
 @dataclass
-class PredeterminedFlags:
+class PredefinedFlags:
+    """
+    Public. A dataclass with predefined flags and most frequently used flags for quick use
+    """
     HELP = Flag(name='help', possible_values=False)
-    SHORT_HELP = Flag(name='h', prefix='-', possible_values=False)
+    SHORT_HELP = Flag(name='H', prefix='-', possible_values=False)
 
     INFO = Flag(name='info', possible_values=False)
-    SHORT_INFO = Flag(name='i', prefix='-', possible_values=False)
+    SHORT_INFO = Flag(name='I', prefix='-', possible_values=False)
 
     ALL = Flag(name='all', possible_values=False)
-    SHORT_ALL = Flag(name='a', prefix='-', possible_values=False)
+    SHORT_ALL = Flag(name='A', prefix='-', possible_values=False)
 
     HOST = Flag(name='host', possible_values=re.compile(r'^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$'))
-    SHORT_HOST = Flag(name='h', prefix='-', possible_values=re.compile(r'^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$'))
+    SHORT_HOST = Flag(name='H', prefix='-', possible_values=re.compile(r'^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$'))
 
     PORT = Flag(name='port', possible_values=re.compile(r'^\d{1,5}$'))
-    SHORT_PORT = Flag(name='p', prefix='-', possible_values=re.compile(r'^\d{1,5}$'))
+    SHORT_PORT = Flag(name='P', prefix='-', possible_values=re.compile(r'^\d{1,5}$'))

argenta/command/flag/models.py

@@ -2,20 +2,38 @@ from typing import Literal, Pattern
 from abc import ABC, abstractmethod
 
 
-class BaseFlag:
+class BaseFlag(ABC):
     def __init__(self, name: str,
-                 prefix: Literal['-', '--', '---'] = '--'):
+                 prefix: Literal['-', '--', '---'] = '--') -> None:
+        """
+        Private. Base class for flags
+        :param name: the name of the flag
+        :param prefix: the prefix of the flag
+        :return: None
+        """
         self._name = name
         self._prefix = prefix
 
-    def get_string_entity(self):
+    def get_string_entity(self) -> str:
+        """
+        Public. Returns a string representation of the flag
+        :return: string representation of the flag as str
+        """
         string_entity: str = self._prefix + self._name
         return string_entity
 
-    def get_name(self):
+    def get_name(self) -> str:
+        """
+        Public. Returns the name of the flag
+        :return: the name of the flag as str
+        """
         return self._name
 
-    def get_prefix(self):
+    def get_prefix(self) -> str:
+        """
+        Public. Returns the prefix of the flag
+        :return: the prefix of the flag as str
+        """
         return self._prefix
 
 
@@ -24,13 +42,29 @@ class InputFlag(BaseFlag):
     def __init__(self, name: str,
                  prefix: Literal['-', '--', '---'] = '--',
                  value: str = None):
+        """
+        Public. The entity of the flag of the entered command
+        :param name: the name of the input flag
+        :param prefix: the prefix of the input flag
+        :param value: the value of the input flag
+        :return: None
+        """
         super().__init__(name, prefix)
         self._flag_value = value
 
     def get_value(self) -> str | None:
+        """
+        Public. Returns the value of the flag
+        :return: the value of the flag as str
+        """
         return self._flag_value
 
     def set_value(self, value):
+        """
+        Private. Sets the value of the flag
+        :param value: the fag value to set
+        :return: None
+        """
         self._flag_value = value
 
 
@@ -38,11 +72,23 @@ class InputFlag(BaseFlag):
 class Flag(BaseFlag):
     def __init__(self, name: str,
                  prefix: Literal['-', '--', '---'] = '--',
-                 possible_values: list[str] | Pattern[str] | False = True):
+                 possible_values: list[str] | Pattern[str] | False = True) -> None:
+        """
+        Public. The entity of the flag being registered for subsequent processing
+        :param name: The name of the flag
+        :param prefix: The prefix of the flag
+        :param possible_values: The possible values of the flag, if False then the flag cannot have a value
+        :return: None
+        """
         super().__init__(name, prefix)
         self.possible_values = possible_values
 
     def validate_input_flag_value(self, input_flag_value: str | None):
+        """
+        Private. Validates the input flag value
+        :param input_flag_value: The input flag value to validate
+        :return: whether the entered flag is valid as bool
+        """
         if self.possible_values is False:
             if input_flag_value is None:
                 return True
@@ -69,22 +115,44 @@ class Flag(BaseFlag):
 
 
 class BaseFlags(ABC):
+    """
+    Private. Base class for groups of flags
+    """
     __slots__ = ('_flags',)
 
     @abstractmethod
     def get_flags(self):
+        """
+        Public. Returns a list of flags
+        :return: list of flags
+        """
         pass
 
     @abstractmethod
     def add_flag(self, flag: Flag | InputFlag):
+        """
+        Public. Adds a flag to the list of flags
+        :param flag: flag to add
+        :return: None
+        """
         pass
 
     @abstractmethod
     def add_flags(self, flags: list[Flag] | list[InputFlag]):
+        """
+        Public. Adds a list of flags to the list of flags
+        :param flags: list of flags to add
+        :return: None
+        """
         pass
 
     @abstractmethod
     def get_flag(self, name: str):
+        """
+        Public. Returns the flag entity by its name or None if not found
+        :param name: the name of the flag to get
+        :return: entity of the flag or None
+        """
         pass
 
     def __iter__(self):
@@ -100,6 +168,11 @@ class BaseFlags(ABC):
 
 class Flags(BaseFlags, ABC):
     def __init__(self, *flags: Flag):
+        """
+        Public. A model that combines the registered flags
+        :param flags: the flags that will be registered
+        :return: None
+        """
         self._flags = flags if flags else []
 
     def get_flags(self) -> list[Flag]:
@@ -121,6 +194,11 @@ class Flags(BaseFlags, ABC):
 
 class InputFlags(BaseFlags, ABC):
     def __init__(self, *flags: InputFlag):
+        """
+        Public. A model that combines the input flags of the input command
+        :param flags: all input flags
+        :return: None
+        """
         self._flags = flags if flags else []
 
     def get_flags(self) -> list[InputFlag]:

argenta/command/models.py

@@ -1,7 +1,7 @@
 from argenta.command.flag.models import Flag, InputFlag, Flags, InputFlags
 from argenta.command.exceptions import (UnprocessedInputFlagException,
-                                         RepeatedInputFlagsException,
-                                         EmptyInputCommandException)
+                                        RepeatedInputFlagsException,
+                                        EmptyInputCommandException)
 from typing import Generic, TypeVar, cast, Literal
 
 
@@ -9,10 +9,18 @@ InputCommandType = TypeVar('InputCommandType')
 
 
 class BaseCommand:
-    def __init__(self, trigger: str):
+    def __init__(self, trigger: str) -> None:
+        """
+        Private. Base class for all commands
+        :param trigger: A string trigger, which, when entered by the user, indicates that the input corresponds to the command
+        """
         self._trigger = trigger
 
     def get_trigger(self) -> str:
+        """
+        Public. Returns the trigger of the command
+        :return: the trigger of the command as str
+        """
         return self._trigger
 
 
@@ -21,18 +29,38 @@ class Command(BaseCommand):
                  description: str = None,
                  flags: Flag | Flags = None,
                  aliases: list[str] = None):
+        """
+        Public. The command that can and should be registered in the Router
+        :param trigger: A string trigger, which, when entered by the user, indicates that the input corresponds to the command
+        :param description: the description of the command
+        :param flags: processed commands
+        :param aliases: string synonyms for the main trigger
+        """
         super().__init__(trigger)
         self._registered_flags: Flags = flags if isinstance(flags, Flags) else Flags(flags) if isinstance(flags, Flag) else Flags()
         self._description = f'Description for "{self._trigger}" command' if not description else description
-        self._aliases = aliases
+        self._aliases = aliases if isinstance(aliases, list) else []
 
     def get_registered_flags(self) -> Flags:
+        """
+        Private. Returns the registered flags
+        :return: the registered flags as Flags
+        """
         return self._registered_flags
 
-    def get_aliases(self) -> list[str] | None:
+    def get_aliases(self) -> list[str] | list:
+        """
+        Public. Returns the aliases of the command
+        :return: the aliases of the command as list[str] | list
+        """
         return self._aliases
 
-    def validate_input_flag(self, flag: InputFlag):
+    def validate_input_flag(self, flag: InputFlag) -> bool:
+        """
+        Private. Validates the input flag
+        :param flag: input flag for validation
+        :return: is input flag valid as bool
+        """
         registered_flags: Flags | None = self.get_registered_flags()
         if registered_flags:
             if isinstance(registered_flags, Flag):
@@ -49,6 +77,10 @@ class Command(BaseCommand):
         return False
 
     def get_description(self) -> str:
+        """
+        Private. Returns the description of the command
+        :return: the description of the command as str
+        """
         return self._description
 
 
@@ -56,18 +88,38 @@ class Command(BaseCommand):
 class InputCommand(BaseCommand, Generic[InputCommandType]):
     def __init__(self, trigger: str,
                  input_flags: InputFlag | InputFlags = None):
+        """
+        Private. The model of the input command, after parsing
+        :param trigger:the trigger of the command
+        :param input_flags: the input flags
+        :return: None
+        """
         super().__init__(trigger)
         self._input_flags: InputFlags = input_flags if isinstance(input_flags, InputFlags) else InputFlags(input_flags) if isinstance(input_flags, InputFlag) else InputFlags()
 
-    def _set_input_flags(self, input_flags: InputFlags):
+    def _set_input_flags(self, input_flags: InputFlags) -> None:
+        """
+        Private. Sets the input flags
+        :param input_flags: the input flags to set
+        :return: None
+        """
         self._input_flags = input_flags
 
     def get_input_flags(self) -> InputFlags:
+        """
+        Private. Returns the input flags
+        :return: the input flags as InputFlags
+        """
         return self._input_flags
 
 
     @staticmethod
     def parse(raw_command: str) -> InputCommandType:
+        """
+        Private. Parse the raw input command
+        :param raw_command: raw input command
+        :return: model of the input command, after parsing as InputCommand
+        """
         if not raw_command:
             raise EmptyInputCommandException()
 

argenta/orchestrator/__init__.py

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

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,6 @@
+__all__ = ["BooleanArgument", "PositionalArgument", "OptionalArgument"]
+
+
+from argenta.orchestrator.argparser.arguments.models import (BooleanArgument,
+                                                             PositionalArgument,
+                                                             OptionalArgument)

argenta/orchestrator/argparser/arguments/models.py

@@ -0,0 +1,55 @@
+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,49 @@
+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,36 @@
+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/router/__init__.py

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

argenta/router/command_handler/entity.py

@@ -1,21 +1,79 @@
 from typing import Callable
+
 from argenta.command import Command
-from argenta.command.flag.models import InputFlags
+from argenta.command.flag import InputFlags
+
 
 
 class CommandHandler:
     def __init__(self, handler: Callable[[], None] | Callable[[InputFlags], 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):
+    def handling(self, input_flags: InputFlags = None) -> None:
+        """
+        Private. Direct processing of an input command
+        :param input_flags: the flags of the input command
+        :return: None
+        """
         if input_flags is not None:
             self._handler(input_flags)
         else:
             self._handler()
 
-    def get_handler(self):
+    def get_handler(self) -> Callable[[], None] | Callable[[InputFlags], None]:
+        """
+        Private. Returns the handler being called
+        :return: the handler being called as Callable[[], None] or Callable[[InputFlags], 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_command_handlers(self) -> list[CommandHandler]:
+        """
+        Private. Returns the list of CommandHandlers
+        :return: the list of CommandHandlers as list[CommandHandler]
+        """
+        return self.command_handlers
+
+    def add_command_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 add_command_handlers(self, *command_handlers: CommandHandler) -> None:
+        """
+        Private. Extend a many CommandHandler to the list of CommandHandlers
+        :param command_handlers: many CommandHandler to be added
+        :return: None
+        """
+        self.command_handlers.extend(command_handlers)
+
+    def __iter__(self):
+        return iter(self.command_handlers)
+
+    def __next__(self):
+        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:')