untils 1.0.0__py3-none-any.whl

untils/ioreader.py

@@ -0,0 +1,55 @@
+"""ioreader.py - IO operations through `IOReader` and their mixins for config extensions."""
+
+# pylint: disable=too-few-public-methods
+
+from typing import Dict, override
+
+import json
+import os
+
+from untils.utils.type_aliases import UnknownConfigType, ConfigSupportedExtensions
+from untils.iovalidator import IOValidator
+from untils.utils.protocols import IOReaderMixin, IOReaderProtocol
+
+from untils.settings import Settings
+
+class JSONMixin(IOReaderMixin):
+    """The JSON extension for `IOReader`."""
+
+    @override
+    @staticmethod
+    def read(settings: Settings, file_path: str) -> UnknownConfigType:
+        with open(file_path, 'r', encoding='utf-8') as file:
+            content: UnknownConfigType = json.loads(file.read())
+        return content
+
+class IOReader():
+    """Reader class for config loading by paths and settings."""
+
+    _MIXINS: Dict[ConfigSupportedExtensions, IOReaderProtocol] = {
+        ".json": JSONMixin,
+        ".json5": JSONMixin
+    }
+    """All supported mixins for `IOReader`."""
+
+    @staticmethod
+    def read_file(settings: Settings, file_path: str) -> UnknownConfigType:
+        """Reads a config file by path.
+        
+        Args:
+            settings: The settings.
+            file_path: The file path.
+
+        Returns:
+            The raw unvalidated config.
+        """
+
+        IOValidator.validate_config_path(settings, file_path)
+
+        extension: str = os.path.splitext(file_path)[1]
+        content: UnknownConfigType = {}
+
+        if extension in IOReader._MIXINS:
+            content: UnknownConfigType = IOReader._MIXINS[extension].read(settings, file_path)
+
+        return content

untils/iovalidator.py

@@ -0,0 +1,55 @@
+"""iovalidator.py - `IOValidator` for IO validations."""
+
+# pylint: disable=too-few-public-methods
+
+import os
+
+from untils.utils.enums import WarningsLevel
+from untils.utils.constants import Constants, Strings
+from untils.utils.lib_warnings import FileWarning, FileError
+
+from untils.settings import Settings
+
+class IOValidator:
+    """Validator class for the all IO operations for `IOReader`."""
+
+    @staticmethod
+    def validate_config_path(settings: Settings, file_path: str) -> bool:
+        """Validates a config path.
+        
+        Args:
+            settings: The settings.
+            file_path: The file path.
+
+        Returns:
+            `True` if the config path is valid and supported, else `False`.
+
+        Raises:
+            FileWarning: The config file is not exists or the config extension is not in standart.
+
+            FileError: The config file is not exists.
+        """
+
+        if os.path.exists(file_path) and os.path.isfile(file_path):
+            # Processing the config file path.
+            extension: str = os.path.splitext(file_path)[1]
+            if extension in Constants.SUPPORTED_CONFIG_FORMATS:
+                if extension not in Constants.STANDART_CONFIG_FORMATS:
+                    # The config format is not in standart.
+                    settings.warning(
+                        Strings.CONFIG_EXTENSION_NOT_SUPPORTS,
+                        Strings.AUTO_CORRECT_WITH_ACCEPTING,
+                        FileWarning,
+                        warning_levels=(WarningsLevel.BASIC, WarningsLevel.STRICT),
+                        exception_levels=()
+                    )
+                return True
+        else:
+            settings.warning(
+                Strings.CONFIG_FILE_NOT_EXISTS,
+                Strings.AUTO_CORRECT_WITH_SKIPPING,
+                FileWarning,
+                FileError
+            )
+
+        return False

untils/parser.py

@@ -0,0 +1,138 @@
+"""parser.py - Parses config and input."""
+
+from typing import Dict, List, Any, cast, get_args, Optional
+
+from untils.utils.type_aliases import (
+    CommandClass, CommandType, ConfigType, InternalCommandStates, InputDict
+)
+from untils.utils.protocols import FinalInputProtocol
+from untils.utils.enums import FinalTokenType
+
+from untils.command import CommandNode, AliasNode, StateNode
+from untils.factories import CommandNodeFactory
+from untils.commands_config import CommandsConfig
+from untils.input_token import FinalInputTokenWord, FinalInputTokenFlag, FinalInputTokenOption
+from untils.settings import Settings
+
+class Parser:
+    """This class parses raw data to intermediate reference."""
+
+    @staticmethod
+    def parse_commands(commands: Dict[str, CommandClass]) -> List[CommandNode]:
+        """Parses a command dictionary to the AST tree of command nodes.
+        
+        Args:
+            commands: The commands dictionary.
+
+        Returns:
+            Parsed AST tree of the command nodes.
+        """
+
+        def parse_command(name: str, command_dict: CommandClass) -> CommandNode:
+            """Parses a single command.
+            
+            Args:
+                name: The command name.
+                command_dict: The command dictionary.
+
+            Returns:
+                The command node.
+            """
+
+            command_type: CommandType = command_dict.get("type")
+            aliases: List[AliasNode] = []
+            default: Any = None
+            children: List[CommandNode] = []
+
+            if command_type in ("word", "flag", "option"):
+                aliases = [AliasNode(name, alias) for alias in command_dict.get("aliases", [])]
+
+            if command_type in ("flag", "option"):
+                default: Any = command_dict.get("default", None)
+
+            if command_type in ("word", "fallback"):
+                children: List[CommandNode] = []
+
+                for child_name, child_dict in command_dict.get("children", {}).items():
+                    children.append(parse_command(child_name, cast(CommandClass, child_dict)))
+
+            return CommandNodeFactory.create(name, command_type, aliases, default, children)
+
+        return [parse_command(name, command_dict) for name, command_dict in commands.items()]
+
+    @staticmethod
+    def parse_states(states_dict: Dict[str, List[str]]) -> List[StateNode]:
+        """Parses states in config.
+        
+        Args:
+            states_dict: The states dictionary.
+
+        Returns:
+            The list of the state nodes.
+        """
+
+        return [
+            StateNode(state, state in get_args(InternalCommandStates), aliases)
+            for state, aliases in states_dict.items()
+        ]
+
+    @staticmethod
+    def parse_config(config_dict: ConfigType) -> CommandsConfig:
+        """Parses a validated config.
+        
+        Args:
+            config_dict: The config dictionary.
+
+        Returns:
+            The parsed config.
+        """
+
+        return CommandsConfig(
+            config_dict["version"],
+            Parser.parse_states(config_dict["states"]),
+            Parser.parse_commands(config_dict["commands"])
+        )
+
+    @staticmethod
+    def parse_input(settings: Settings, tokens: List[FinalInputProtocol]) -> InputDict:
+        """Parses a user input to input dictionary.
+        
+        Args:
+            tokens: Final tokenized tokens.
+            debug: Determines debug messages display.
+
+        Returns:
+            The parsed input dictionary.
+        """
+
+        settings.logger.debug(f"Parser.parse_input(tokens={tokens}).")
+
+        path: List[str] = []
+        flags: Dict[str, Optional[bool]] = {}
+        options: Dict[str, Any] = {}
+
+        i: int = 0
+        while i < len(tokens):
+            settings.logger.debug(f"Iteration: {i}.")
+
+            token: FinalInputProtocol = tokens[i]
+
+            if token.type == FinalTokenType.WORD and isinstance(token, FinalInputTokenWord):
+                settings.logger.debug("Process `Word` token.")
+                path.append(token.value)
+
+            elif token.type == FinalTokenType.FLAG and isinstance(token, FinalInputTokenFlag):
+                settings.logger.debug("Process `Flag` token.")
+                flags[token.name] = token.value
+
+            elif token.type == FinalTokenType.OPTION and isinstance(token, FinalInputTokenOption):
+                settings.logger.debug("Process `Option` token.")
+                options[token.name] = token.value
+
+            i += 1
+
+        return {
+            "path": path,
+            "flags": flags,
+            "options": options
+        }

untils/processor.py

@@ -0,0 +1,88 @@
+"""processor.py - `Processor` class for universal pipe-lines."""
+
+from typing import List, Optional
+
+from untils.utils.type_aliases import UnknownConfigType, ConfigType, InputDict
+from untils.utils.protocols import FinalInputProtocol
+
+from untils.ioreader import IOReader
+from untils.config_validator import ConfigValidator
+from untils.parser import Parser
+from untils.commands_config import CommandsConfig
+from untils.settings import Settings
+from untils.input_token import RawInputToken
+from untils.tokenizer import Tokenizer
+from untils.input_validator import InputValidator
+
+class Processor:
+    """Processor class for config processing."""
+
+    @staticmethod
+    def load_config(settings: Settings, file_path: str) -> CommandsConfig:
+        """Loads config.
+        
+        Args:
+            settings: The settings.
+            file_path: The file path.
+            debug: Determines debug messages display.
+        
+        Returns:
+            Validated and parsed config.
+        """
+
+        settings.logger.debug(f"Load config by path: '{file_path}'.")
+
+        ### 1. IOReader ###
+        settings.logger.debug("Reading the file.")
+        content: UnknownConfigType = IOReader.read_file(settings, file_path)
+        settings.logger.debug(f"Content: {content}.")
+
+        ### 2. ConfigValidator ###
+        settings.logger.debug("Validating the config.")
+        raw_config: ConfigType = ConfigValidator.validate_config(settings, content)
+        settings.logger.debug(f"Intermediate config: {raw_config}.")
+
+        ### 3. Parser ###
+        settings.logger.debug("Parsing.")
+        config: CommandsConfig = Parser.parse_config(raw_config)
+        settings.logger.debug(f"Parsed config: {config}.")
+
+        return config
+
+    @staticmethod
+    def process_input(
+        settings: Settings,
+        config: Optional[CommandsConfig],
+        input_str: str
+    ) -> InputDict:
+        """Validates a user input.
+        
+        Args:
+            settings: The settings.
+            input_str: The user input.
+            debug: Determines debug messages display.
+
+        Returns:
+            Validated and parsed input dict.
+        """
+
+        settings.logger.debug(f"Processing input string: '{input_str}'.")
+
+        ### 1. Tokenizer ###
+        settings.logger.debug("Tokenizing the input.")
+        tokenizer: Tokenizer = Tokenizer(settings, input_str)
+        tokens: List[RawInputToken] = tokenizer.tokenize_input()
+        settings.logger.debug(f"Tokens: {tokens}.")
+
+        ### 2. InputValidator ###
+        settings.logger.debug("Validating the input.")
+        input_validator: InputValidator = InputValidator(settings, config, tokens)
+        validated_tokens: List[FinalInputProtocol] = input_validator.validate_input(settings)
+        settings.logger.debug(f"Validated tokens: {validated_tokens}.")
+
+        ### 3. Parser ###
+        settings.logger.debug("Parsing the input.")
+        parsed_representation: InputDict = Parser.parse_input(settings, validated_tokens)
+        settings.logger.debug(f"Parsed input: {parsed_representation}.")
+
+        return parsed_representation

untils/settings.py

@@ -0,0 +1,114 @@
+"""settings.py - Global context settings for much part of all library."""
+
+# pyright: reportUnnecessaryIsInstance=false
+
+from typing import Optional, Tuple, Type, Union
+
+import warnings
+import logging
+
+from untils.utils.enums import WarningsLevel, InternalState
+from untils.utils.decorators import alternative
+from untils.utils.constants import Strings
+from untils.utils.lib_warnings import ConfigError, ConfigWarning
+
+class Settings:
+    """The global context settings."""
+
+    __slots__ = ["__warnings_level", "__current_state", "__logger"]
+
+    __warnings_level: WarningsLevel
+    __current_state: str
+    __logger: logging.Logger
+
+    @property
+    def warnings_level(self) -> WarningsLevel:
+        """Warnings level, which defines strictness of code flow."""
+        return self.__warnings_level
+
+    @warnings_level.setter
+    def warnings_level(self, value: WarningsLevel) -> None:
+        self.__warnings_level = value
+
+    @property
+    def current_state(self) -> str:
+        """Current commands state."""
+        return self.__current_state
+
+    @current_state.setter
+    def current_state(self, value: Union[str, InternalState]) -> None:
+        if isinstance(value, str):
+            if value != InternalState.INIT.value:
+                self.warning(
+                    Strings.INVALID_INTERNAL_STATE_CHANGE.substitute(state=value),
+                    Strings.AUTO_CORRECT_TO_LATEST,
+                    RuntimeWarning,
+                    ValueError
+                )
+            else:
+                self.__current_state = value
+        elif isinstance(value, InternalState):
+            if value != InternalState.INIT:
+                self.warning(
+                    Strings.INVALID_INTERNAL_STATE_CHANGE.substitute(state=value),
+                    Strings.AUTO_CORRECT_TO_LATEST,
+                    RuntimeWarning,
+                    ValueError
+                )
+            else:
+                self.__current_state = value.value
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Returns settings logger."""
+        return self.__logger
+
+    def __init__(self) -> None:
+        self.__warnings_level = WarningsLevel.STRICT
+        self.__current_state = InternalState.INIT.value
+        self.__logger = logging.getLogger(__name__)
+        self.__logger.debug(Strings.LOG_SETTINGS_INIT)
+
+    @alternative(version=Strings.ANY_VERSION)
+    def get_warnings_level(self) -> WarningsLevel:
+        """[!ALT] Get a warnings level.\n
+        <This method is alternative for the standart. In real product use the property `Settings.warnings_level`.>
+        
+        Returns:
+            The current warnings level.
+        """
+
+        return self.__warnings_level
+
+    @alternative(version=Strings.ANY_VERSION)
+    def set_warnings_level(self, warnings_level: WarningsLevel=WarningsLevel.STRICT) -> None:
+        """[!ALT] Sets a warnings level.\n
+        <This method is alternative for the standart. In real product use the property `Settings.warnings_level`.>
+        
+        Args:
+            warnings_level: The warnings level.
+        """
+
+        self.__warnings_level = warnings_level
+
+    def warning(
+        self,
+        message: str,
+        auto_correct: str,
+        warning_type: Type[Warning]=ConfigWarning,
+        exception_type: Type[Exception]=ConfigError,
+        warning_levels: Optional[Union[Tuple[WarningsLevel, ...], Tuple[None]]]=None,
+        exception_levels: Optional[Union[Tuple[WarningsLevel, ...], Tuple[None]]]=None
+    ) -> None:
+        """Warning or exception in validators."""
+
+        if self.warnings_level in (warning_levels or (WarningsLevel.BASIC,)):
+            self.logger.warning(message + ' ' + auto_correct, stacklevel=3)
+            warnings.warn(
+                message + ' ' + auto_correct,
+                warning_type,
+                stacklevel=3
+            )
+        elif self.warnings_level in (exception_levels or (WarningsLevel.STRICT,)):
+            self.logger.error(message, stacklevel=3)
+            raise exception_type(message)

untils/tokenizer.py

@@ -0,0 +1,108 @@
+"""tokenizer.py - Tokenize raw user input string to raw tokens."""
+
+from typing import List, Literal, cast
+
+from untils.utils.enums import RawTokenType
+from untils.input_token import RawInputToken
+
+from untils.settings import Settings
+
+class Tokenizer:
+    """Tokenizer class, which tokenizes user input."""
+
+    __slots__ = ["_settings", "_input_str", "_result", "_i"]
+
+    _settings: Settings
+    """The settings."""
+    _input_str: str
+    """The user input string."""
+    _result: List[RawInputToken]
+    """The processed raw tokens."""
+    _i: int
+    """Tokenize index."""
+
+    def __init__(self, settings: Settings, input_str: str) -> None:
+        """
+        Args:
+            input_str: The user input.
+            debug: Determines debug messages display.
+        """
+
+        self._settings = settings
+        self._input_str = input_str
+        self._result = []
+        self._i = 0
+
+    def tokenize_string(self) -> None:
+        """Tokenizes the `String` type."""
+
+        string_char: Literal['\'', '\"'] = cast(Literal['\'', '\"'], self._input_str[self._i])
+        self._i += 1
+        string: str = ""
+
+        while self._i < len(self._input_str) and self._input_str[self._i] != string_char:
+            if self._input_str[self._i] == '\\':
+                if self._input_str[self._i + 1] in ('\'', '\"'):
+                    string += self._input_str[self._i + 1]
+                elif self._input_str[self._i + 1] == '\\':
+                    string += self._input_str[self._i]
+
+                self._i += 1
+            else:
+                string += self._input_str[self._i]
+
+            self._i += 1
+
+        self._result.append(RawInputToken(RawTokenType.STRING, string))
+        self._settings.logger.debug(f"String: '{string}'")
+
+    def tokenize_word(self) -> None:
+        """Tokenizes the `Word` type."""
+
+        start: int = self._i
+
+        while self._i < len(self._input_str) and self._input_str[self._i].isalnum():
+            self._i += 1
+
+        word: str = self._input_str[start:self._i]
+        self._result.append(RawInputToken(RawTokenType.WORD, word))
+        self._settings.logger.debug(f"Word: '{word}'")
+
+    def tokenize_input(self) -> List[RawInputToken]:
+        """Tokenizes the input.
+        
+        Returns:
+            Unvalidated raw tokens.
+        """
+
+        self._settings.logger.debug(f"Tokenizer.tokenize_input(input_str='{self._input_str}')")
+
+        self._result = []
+        self._i = 0
+        while self._i < len(self._input_str):
+            self._settings.logger.debug(f"Current character: {self._input_str[self._i]}.")
+
+            if self._input_str[self._i] == ' ':
+                self._settings.logger.debug("Process Space character.")
+                self._result.append(RawInputToken(RawTokenType.SPACE, ' '))
+
+            elif self._input_str[self._i] == '-':
+                self._settings.logger.debug("Process Minus character.")
+                self._result.append(RawInputToken(RawTokenType.MINUS, '-'))
+
+            if self._input_str[self._i] == '!':
+                self._settings.logger.debug("Process Not character.")
+                self._result.append(RawInputToken(RawTokenType.NOT, '!'))
+
+            elif self._input_str[self._i] in ('\'', '\"'):
+                self._settings.logger.debug("Process `String` construction.")
+                self.tokenize_string()
+
+            elif self._input_str[self._i].isalnum():
+                self._settings.logger.debug("Process `Word` construction.")
+                self.tokenize_word()
+                continue
+
+            self._i += 1
+
+        return self._result

untils/utils/__init__.py

@@ -0,0 +1,22 @@
+"""This module represents all tools, which need for main module."""
+
+# pyright: reportUnusedImport=false
+# ^^^^^^^ (Public imports.)
+
+from untils.utils.lib_warnings import (
+    ConfigWarning, FileWarning, ConfigStructureWarning, ConfigValuesWarning, InputWarning,
+    InputStructureWarning,InputValuesWarning, ConfigError, FileError, ConfigStructureError,
+    ConfigValuesError, InputError, InputStructureError, InputValuesError
+)
+from untils.utils.type_aliases import (
+    ConfigVersion, CommandClass, UnknownCommandClass, CommandType,
+    InternalCommandStates, CommandStates, ConfigSupportedExtensions, UnknownCommandConfig,
+    WordCommandConfig, FallbackCommandConfig, FlagCommandConfig, OptionCommandConfig,
+    ConfigType, UnknownConfigType, InputDict, CommandPath
+)
+from untils.utils.constants import Constants, Strings
+from untils.utils.decorators import deprecated, alternative
+from untils.utils.enums import (
+    WarningsLevel, ConfigVersions, RawTokenType, FinalTokenType, InternalState
+)
+from untils.utils.protocols import IOReaderMixin, Factoric, FinalInputProtocol