orionis 0.285.0__py3-none-any.whl → 0.287.0__py3-none-any.whl

orionis/services/environment/exceptions/environment_value_exception.py

@@ -0,0 +1,23 @@
+class OrionisEnvironmentValueException(Exception):
+
+    def __init__(self, msg: str):
+        """
+        Exception raised for errors related to environment values.
+
+        Parameters
+        ----------
+        msg : str
+            The error message describing the exception.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the exception.
+
+        Returns
+        -------
+        str
+            A formatted string with the exception class name and its first argument.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/services/environment/type_hint.py

@@ -0,0 +1,559 @@
+from orionis.services.environment.exceptions.environment_value_error import OrionisEnvironmentValueError
+from orionis.services.environment.exceptions.environment_value_exception import OrionisEnvironmentValueException
+
+class EnvTypes:
+
+    # Type class to handle different types of environment variables
+    OPTIONS = {
+        'path',
+        'str',
+        'int',
+        'float',
+        'bool',
+        'list',
+        'dict',
+        'tuple',
+        'set'
+    }
+
+    @staticmethod
+    def options() -> set:
+        """
+        Returns the set of valid type hints that can be used with this Type class.
+
+        Returns
+        -------
+        set
+            A set containing the valid type hints.
+        """
+        return EnvTypes.OPTIONS
+
+    def __init__(self, raw: str = None):
+        """
+        Parse a raw string input into a type hint and value string.
+
+        Parameters
+        ----------
+        raw : str, optional
+            String that may contain a type hint and value separated by a colon (e.g., "int: 42").
+            If a colon is present, the part before the colon is treated as the type hint and the part after as the value.
+            If no colon is present, the entire string is treated as the value with no type hint.
+
+        Attributes
+        ----------
+        __type_hint : str or None
+            The extracted type hint in lowercase, or None if not provided.
+        __value_str : str or None
+            The extracted value string, or None if not provided.
+        """
+        type_hint, value_str = raw.split(':', 1)
+        if type_hint.strip().lower() in self.OPTIONS:
+            self.__type_hint = type_hint.strip().lower()
+            self.__value_str = value_str.strip() if value_str else None
+        else:
+            self.__type_hint = None
+            self.__value_str = raw.strip() if raw else None
+
+    def to(self, type_hint: str):
+        """
+        Set the type hint for the Type instance.
+
+        Parameters
+        ----------
+        type_hint : str
+            The type hint to set, which must be one of the valid options defined in OPTIONS.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the provided type hint is not one of the valid options.
+        """
+
+        # Validate and set the type hint
+        type_hint = type_hint.strip().lower()
+        if type_hint not in self.OPTIONS:
+            raise OrionisEnvironmentValueError(f"Invalid type hint: {type_hint}. Must be one of {self.OPTIONS}.")
+        self.__type_hint = type_hint
+
+        # Parse the value to the specified type hint
+        if self.__type_hint == 'path':
+            return self.__toPath()
+
+        if self.__type_hint == 'str':
+            return self.__toStr()
+
+        if self.__type_hint == 'int':
+            return self.__toInt()
+
+        if self.__type_hint == 'float':
+            return self.__toFloat()
+
+        if self.__type_hint == 'bool':
+            return self.__toBool()
+
+        if self.__type_hint == 'list':
+            return self.__toList()
+
+        if self.__type_hint == 'dict':
+            return self.__toDict()
+
+        if self.__type_hint == 'tuple':
+            return self.__toTuple()
+
+        if self.__type_hint == 'set':
+            return self.__toSet()
+
+    def hasValidTypeHint(self) -> bool:
+        """
+        Check if the type hint is valid.
+
+        Returns
+        -------
+        bool
+            True if the type hint is valid (exists in the OPTIONS set), False otherwise.
+        """
+        return self.__type_hint in self.OPTIONS
+
+    def explode(self) -> tuple:
+        """
+        Returns a tuple containing the type hint and value string.
+
+        Returns
+        -------
+        tuple
+            A tuple (type_hint, value_str) where:
+                type_hint : str or None
+                    The extracted type hint in lowercase, or None if not provided.
+                value_str : str or None
+                    The extracted value string, or None if not provided.
+        """
+        return self.__type_hint, self.__value_str
+
+    def __parsePath(self):
+        """
+        Returns the value as a string, assuming the type hint is 'path:'.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            The value string with backslashes replaced by forward slashes, if the type hint is 'path:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be processed as a path.
+        """
+        return self.__value_str.replace('\\', '/').strip()
+
+    def __toPath(self):
+        """
+        Converts the internal string value to a formatted path string.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value, with backslashes replaced by forward slashes.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a string.
+        """
+        if not isinstance(self.__value_str, str):
+            raise OrionisEnvironmentValueError(f"Value must be a string to convert to path, got {type(self.__value_str).__name__} instead.")
+        value = self.__value_str.replace('\\', '/').strip()
+        return f"{self.__type_hint}:{value}"
+
+    def __parseStr(self):
+        """
+        Returns the value as a string, assuming the type hint is 'str:'.
+
+        Returns
+        -------
+        str
+            The value string if the type hint is 'str:', otherwise raises an error.
+        """
+        return self.__value_str.strip()
+
+    def __toStr(self):
+        """
+        Converts the internal value to a string representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a string.
+        """
+        if not isinstance(self.__value_str, str):
+            raise OrionisEnvironmentValueError(f"Value must be a string to convert to str, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{self.__value_str}"
+
+    def __parseInt(self):
+        """
+        Returns the value as an integer, assuming the type hint is 'int:'.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        int
+            The value converted to an integer if the type hint is 'int:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be converted to an integer.
+        """
+        value = self.__value_str.strip()
+        try:
+            return int(value)
+        except ValueError as e:
+            raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to int: {str(e)}")
+
+    def __toInt(self):
+        """
+        Converts the internal value to an integer representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value as an integer.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a string or cannot be converted to an integer.
+        """
+        if not isinstance(self.__value_str, int):
+            raise OrionisEnvironmentValueError(f"Value must be an integer to convert to int, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{str(self.__value_str)}"
+
+    def __parseFloat(self):
+        """
+        Returns the value as a float, assuming the type hint is 'float:'.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        float
+            The value converted to a float if the type hint is 'float:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be converted to a float.
+        """
+        value = self.__value_str.strip()
+        try:
+            return float(value)
+        except ValueError as e:
+            raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to float: {str(e)}")
+
+    def __toFloat(self):
+        """
+        Converts the internal value to a float representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value as a float.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a string or cannot be converted to a float.
+        """
+        if not isinstance(self.__value_str, float):
+            raise OrionisEnvironmentValueError(f"Value must be a float to convert to float, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{str(self.__value_str)}"
+
+    def __parseBool(self):
+        """
+        Returns the value as a boolean, assuming the type hint is 'bool:'.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        bool
+            The value converted to a boolean if the type hint is 'bool:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be converted to a boolean.
+        """
+        value = self.__value_str.strip().lower()
+        if value in {'true', '1', 'yes', 'on'}:
+            return True
+        elif value in {'false', '0', 'no', 'off'}:
+            return False
+        else:
+            raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to bool.")
+
+    def __toBool(self):
+        """
+        Converts the internal value to a boolean representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value as a boolean.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a boolean.
+        """
+        if not isinstance(self.__value_str, bool):
+            raise OrionisEnvironmentValueError(f"Value must be a boolean to convert to bool, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{str(self.__value_str).lower()}"
+
+    def __parseList(self):
+        """
+        Returns the value as a list, assuming the type hint is 'list:'.
+
+        Returns
+        -------
+        list
+            The value converted to a list if the type hint is 'list:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be converted to a list.
+        """
+        import ast
+
+        value = self.__value_str.strip()
+        try:
+            parsed = ast.literal_eval(value)
+            if not isinstance(parsed, list):
+                raise ValueError("Value is not a list")
+            return parsed
+        except (ValueError, SyntaxError) as e:
+            raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to list: {str(e)}")
+
+    def __toList(self):
+        """
+        Converts the internal value to a list representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value as a list.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a list.
+        """
+        if not isinstance(self.__value_str, list):
+            raise OrionisEnvironmentValueError(f"Value must be a list to convert to list, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_str)}"
+
+    def __parseDict(self):
+        """
+        Returns the value as a dict, assuming the type hint is 'dict:'.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        dict
+            The value converted to a dict if the type hint is 'dict:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be converted to a dict.
+        """
+        import ast
+
+        value = self.__value_str.strip()
+        try:
+            parsed = ast.literal_eval(value)
+            if not isinstance(parsed, dict):
+                raise ValueError("Value is not a dict")
+            return parsed
+        except (ValueError, SyntaxError) as e:
+            raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to dict: {str(e)}")
+
+    def __toDict(self):
+        """
+        Converts the internal value to a dict representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value as a dict.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a dict.
+        """
+        if not isinstance(self.__value_str, dict):
+            raise OrionisEnvironmentValueError(f"Value must be a dict to convert to dict, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_str)}"
+
+    def __parseTuple(self):
+        """
+        Returns the value as a tuple, assuming the type hint is 'tuple:'.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        tuple
+            The value converted to a tuple if the type hint is 'tuple:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be converted to a tuple.
+        """
+        import ast
+
+        value = self.__value_str.strip()
+        try:
+            parsed = ast.literal_eval(value)
+            if not isinstance(parsed, tuple):
+                raise ValueError("Value is not a tuple")
+            return parsed
+        except (ValueError, SyntaxError) as e:
+            raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to tuple: {str(e)}")
+
+    def __toTuple(self):
+        """
+        Converts the internal value to a tuple representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value as a tuple.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a tuple.
+        """
+        if not isinstance(self.__value_str, tuple):
+            raise OrionisEnvironmentValueError(f"Value must be a tuple to convert to tuple, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_str)}"
+
+    def __parseSet(self):
+        """
+        Returns the value as a set, assuming the type hint is 'set:'.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        set
+            The value converted to a set if the type hint is 'set:'.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If the value cannot be converted to a set.
+        """
+        import ast
+
+        value = self.__value_str.strip()
+        try:
+            parsed = ast.literal_eval(value)
+            if not isinstance(parsed, set):
+                raise ValueError("Value is not a set")
+            return parsed
+        except (ValueError, SyntaxError) as e:
+            raise OrionisEnvironmentValueException(f"Cannot convert '{value}' to set: {str(e)}")
+
+    def __toSet(self):
+        """
+        Converts the internal value to a set representation.
+
+        Returns
+        -------
+        str
+            A string representing the type hint and the value as a set.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the internal value is not a set.
+        """
+        if not isinstance(self.__value_str, set):
+            raise OrionisEnvironmentValueError(f"Value must be a set to convert to set, got {type(self.__value_str).__name__} instead.")
+        return f"{self.__type_hint}:{repr(self.__value_str)}"
+
+    def get(self):
+        """
+        Returns the value corresponding to the specified type hint.
+
+        Checks if the provided type hint is valid and then dispatches the call to the appropriate
+        method for handling the type.
+
+        Supported type hints include: 'path:', 'str:', 'int:', 'float:', 'bool:', 'list:', 'dict:', 'tuple:', and 'set:'.
+
+        Returns
+        -------
+        Any
+            The value converted or processed according to the specified type hint.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the type hint is not one of the supported options.
+        """
+        if not self.__type_hint in self.OPTIONS:
+            raise OrionisEnvironmentValueError(f"Invalid type hint: {self.__type_hint}. Must be one of {self.OPTIONS}.")
+
+        if self.__type_hint == 'path':
+            return self.__parsePath()
+
+        if self.__type_hint == 'str':
+            return self.__parseStr()
+
+        if self.__type_hint == 'int':
+            return self.__parseInt()
+
+        if self.__type_hint == 'float':
+            return self.__parseFloat()
+
+        if self.__type_hint == 'bool':
+            return self.__parseBool()
+
+        if self.__type_hint == 'list':
+            return self.__parseList()
+
+        if self.__type_hint == 'dict':
+            return self.__parseDict()
+
+        if self.__type_hint == 'tuple':
+            return self.__parseTuple()
+
+        if self.__type_hint == 'set':
+            return self.__parseSet()

orionis/test/exceptions/test_config_exception.py

@@ -1,28 +1,19 @@
 class OrionisTestConfigException(Exception):
-    """
-    Custom exception for test configuration errors in the Orionis framework.
-
-    This exception is raised when there is an issue with the test configuration,
-    providing a clear and descriptive error message to aid in debugging.
-    """
 
     def __init__(self, msg: str):
         """
-        Initializes the OrionisTestConfigException with a specific error message.
-
-        Args:
-            msg (str): A descriptive error message explaining the cause of the exception.
+        Parameters
+        ----------
+        msg : str
+            Descriptive error message explaining the cause of the exception.
         """
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Returns a formatted string representation of the exception.
-
-        The string includes the exception name and the error message, providing
-        a clear and concise description of the issue.
-
-        Returns:
-            str: A formatted string describing the exception.
+        Returns
+        -------
+        str
+            Formatted string describing the exception, including the exception name and error message.
         """
         return f"{self.__class__.__name__}: {self.args[0]}"

orionis/test/exceptions/test_failure_exception.py

@@ -1,29 +1,31 @@
 import unittest
 
 class OrionisTestFailureException(Exception):
-    """
-    OrionisTestFailureException is a custom exception class used to handle test failures and errors
-    in a structured manner. It provides detailed information about the failed and errored tests,
-    including their IDs and formatted error messages.
-    Methods:
-        __init__(result: unittest.TestResult):
-        __str__() -> str:
-    """
 
     def __init__(self, result: unittest.TestResult):
         """
-        Initializes the exception with details about failed and errored tests.
-        Args:
-            result (unittest.TestResult): The test result object containing information
-                about test failures and errors.
-        Attributes:
-            failed_tests (list): A list of IDs for tests that failed.
-            errored_tests (list): A list of IDs for tests that encountered errors.
-            error_messages (list): A list of formatted error messages for failed and errored tests.
-            text (str): A formatted string summarizing the test failures and errors.
-        Raises:
-            Exception: An exception with a message summarizing the number of failed
-                and errored tests along with their details.
+        Initialize the exception with details about failed and errored tests.
+
+        Parameters
+        ----------
+        result : unittest.TestResult
+            The test result object containing information about test failures and errors.
+
+        Attributes
+        ----------
+        failed_tests : list
+            List of IDs for tests that failed.
+        errored_tests : list
+            List of IDs for tests that encountered errors.
+        error_messages : list
+            List of formatted error messages for failed and errored tests.
+        text : str
+            Formatted string summarizing the test failures and errors.
+
+        Raises
+        ------
+        Exception
+            If there are failed or errored tests, raises an exception with a summary message.
         """
         failed_tests = [test.id() for test, _ in result.failures]
         errored_tests = [test.id() for test, _ in result.errors]
@@ -40,13 +42,11 @@ class OrionisTestFailureException(Exception):
 
     def __str__(self) -> str:
         """
-        Returns a string representation of the exception.
+        Return a string representation of the exception.
 
-        The string includes the exception name and the first argument
-        passed to the exception, providing a clear description of the
-        test failure.
-
-        Returns:
-            str: A formatted string describing the exception.
+        Returns
+        -------
+        str
+            A formatted string describing the exception, including the exception name and the message.
         """
         return f"{self.__class__.__name__}: {self.args[0]}"