orionis 0.282.0__py3-none-any.whl → 0.284.0__py3-none-any.whl

orionis/application.py

@@ -1,15 +1,10 @@
 from orionis.foundation.config.startup import Configuration
+from orionis.patterns.singleton.meta_class import Singleton
 
-class Orionis:
+class Orionis(metaclass=Singleton):
 
     def __init__(
         self,
         config: Configuration = None
     ):
-        """
-        Initializes the Orionis instance with optional configuration objects.
-
-        Args:
-            config (Configuration, optional): Custom application configuration.
-        """
         self.__config = config or Configuration()

orionis/foundation/config/testing/entities/testing.py

@@ -136,6 +136,15 @@ class Testing:
         }
     )
 
+    persistent_driver: str = field(
+        default='sqlite',
+        metadata={
+            "description": "Specifies the driver to use for persisting test results. Supported values: 'sqlite', 'json'. Default is 'sqlite'.",
+            "required": False,
+            "default": 'sqlite'
+        }
+    )
+
     def __post_init__(self):
         """
         Post-initialization validation for the testing configuration entity.
@@ -202,6 +211,7 @@ class Testing:
             raise OrionisIntegrityException(
             f"Invalid type for 'folder_path': {type(self.folder_path).__name__}. It must be a string or a list of strings representing the folder path pattern."
             )
+
         if isinstance(self.folder_path, list):
             for i, folder in enumerate(self.folder_path):
                 if not isinstance(folder, str):
@@ -230,6 +240,21 @@ class Testing:
                         f"Invalid type for tag at index {i} in 'tags': {type(tag).__name__}. Each tag must be a string."
                     )
 
+        if not isinstance(self.persistent, bool):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'persistent': {type(self.persistent).__name__}. It must be a boolean (True or False)."
+            )
+
+        if not isinstance(self.persistent_driver, str):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'persistent_driver': {type(self.persistent_driver).__name__}. It must be a string."
+            )
+
+        if self.persistent_driver not in ['sqlite', 'json']:
+            raise OrionisIntegrityException(
+                f"Invalid value for 'persistent_driver': {self.persistent_driver}. It must be one of: ['sqlite', 'json']."
+            )
+
     def toDict(self) -> dict:
         """
         Convert the object to a dictionary representation.

orionis/metadata/framework.py

@@ -5,7 +5,7 @@
 NAME = "orionis"
 
 # Current version of the framework
-VERSION = "0.282.0"
+VERSION = "0.284.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"

orionis/services/asynchrony/{async_io.py → coroutines.py}

@@ -1,5 +1,6 @@
 import asyncio
 from typing import Any, Coroutine, TypeVar, Union
+from orionis.services.asynchrony.exceptions.coroutine_exception import OrionisCoroutineException
 
 T = TypeVar("T")
 
@@ -18,7 +19,7 @@ def run_coroutine(coro: Coroutine[Any, Any, T]) -> Union[T, asyncio.Future]:
     from inspect import iscoroutine
 
     if not iscoroutine(coro):
-        raise TypeError("Expected a coroutine object.")
+        raise OrionisCoroutineException("Expected a coroutine object.")
 
     try:
         loop = asyncio.get_running_loop()

orionis/services/asynchrony/exceptions/coroutine_exception.py

@@ -0,0 +1,26 @@
+class OrionisCoroutineException(Exception):
+    """
+    Exception raised for errors related to coroutine operations in the Orionis framework.
+    This exception is intended to signal issues encountered during asynchronous
+    operations, providing a clear and descriptive error message to facilitate debugging.
+        msg (str): A detailed message describing the cause of the exception.
+    Example:
+        raise OrionisCoroutineException("Coroutine execution failed due to timeout.")
+    """
+
+    def __init__(self, msg: str):
+        """
+        Initialize the exception with a custom error message.
+        Args:
+            msg (str): The error message describing the exception.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the exception, including the class name and the first argument.
+
+        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/dot_env.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from typing import Any, Optional, Union
 from dotenv import dotenv_values, load_dotenv, set_key, unset_key
 from orionis.patterns.singleton.meta_class import Singleton
+from orionis.services.environment.exceptions.value_exception import OrionisEnvironmentValueException
 
 class DotEnv(metaclass=Singleton):
     """
@@ -39,7 +40,7 @@ class DotEnv(metaclass=Singleton):
 
             load_dotenv(self._resolved_path)
 
-    def get(self, key: str, default: Optional[Any] = None) -> Any:
+    def get(self, key: str, default: Optional[Any] = None, is_path:bool=False) -> Any:
         """
         Retrieve the value of an environment variable by key.
 
@@ -54,6 +55,8 @@ class DotEnv(metaclass=Singleton):
             key (str): The name of the environment variable to retrieve.
             default (Optional[Any], optional): The value to return if the key is not found.
                 Defaults to None.
+            is_path (bool, optional): If True, the value is treated as a file path and backslashes are replaced with forward slashes.
+                This is useful for Windows paths. Defaults to False.
 
         Returns:
             Any: The parsed value of the environment variable, or the default if not found.
@@ -62,9 +65,9 @@ class DotEnv(metaclass=Singleton):
             value = dotenv_values(self._resolved_path).get(key)
             if value is None:
                 value = os.getenv(key)
-            return self.__parseValue(value) if value is not None else default
+            return self.__parseValue(value, is_path) if value is not None else default
 
-    def set(self, key: str, value: Union[str, int, float, bool, list, dict]) -> bool:
+    def set(self, key: str, value: Union[str, int, float, bool, list, dict], is_path:bool=False) -> bool:
         """
         Sets an environment variable with the specified key and value.
 
@@ -73,13 +76,16 @@ class DotEnv(metaclass=Singleton):
         Args:
             key (str): The name of the environment variable to set.
             value (Union[str, int, float, bool, list, dict]): The value to assign to the environment variable. Supported types include string, integer, float, boolean, list, and dictionary.
+            is_path (bool, optional): If True, the value is treated as a file path and backslashes are replaced with forward slashes.
+            This is useful for Windows paths. Defaults to False.
 
         Returns:
             bool: True if the environment variable was successfully set.
         """
+
         with self._lock:
-            serialized_value = self.__serializeValue(value)
-            set_key(str(self._resolved_path), key, f'"{serialized_value}"', quote_mode="never")
+            serialized_value = self.__serializeValue(value, is_path)
+            set_key(str(self._resolved_path), key, serialized_value)
             os.environ[key] = str(value)
             return True
 
@@ -133,7 +139,7 @@ class DotEnv(metaclass=Singleton):
         with self._lock:
             return base64.b64encode(json.dumps(self.all()).encode()).decode()
 
-    def __parseValue(self, value: Any) -> Any:
+    def __parseValue(self, value: Any, is_path:bool=False) -> Any:
         """
         Parses and converts the input value to an appropriate Python data type.
 
@@ -151,67 +157,91 @@ class DotEnv(metaclass=Singleton):
         """
         if value is None:
             return None
+
         if isinstance(value, (bool, int, float)):
             return value
+
         value_str = str(value).strip()
         if not value_str or value_str.lower() in {'none', 'null', 'nan'}:
             return None
+
         if value_str.lower() == 'true':
             return True
+
         if value_str.lower() == 'false':
             return False
+
+        if is_path:
+            return value_str.replace("\\", "/")
+
         try:
             if value_str.isdigit() or (value_str.startswith('-') and value_str[1:].isdigit()):
                 return int(value_str)
         except Exception:
             pass
+
         try:
             float_val = float(value_str)
             if '.' in value_str or 'e' in value_str.lower():
                 return float_val
         except Exception:
             pass
+
         try:
             return ast.literal_eval(value_str)
         except Exception:
             pass
+
         return value_str
 
-    def __serializeValue(self, value: Any) -> str:
+    def __serializeValue(self, value: Any, is_path:bool=False) -> str:
         """
         Serializes a given value to a string suitable for storage in a .env file.
 
         Parameters:
             value (Any): The value to serialize. Supported types are None, str, bool, int, float, list, and dict.
+            is_path (bool): If True, the value is treated as a file path and backslashes are replaced with forward slashes.
+            This is useful for Windows paths.
 
         Returns:
             str: The serialized string representation of the value.
 
         Raises:
-            ValueError: If a float value is in scientific notation.
-            TypeError: If the value's type is not serializable for .env files.
+            OrionisEnvironmentValueException: If a float value is in scientific notation or  If the value's type is not serializable for .env files.
         """
+        if is_path:
+            return str(value).replace("\\", "/")
+
         if value is None:
             return "None"
+
         if isinstance(value, str):
             return value
+
         if isinstance(value, bool):
             return str(value).lower()
+
         if isinstance(value, int):
             return str(value)
+
         if isinstance(value, float):
             value = str(value)
             if 'e' in value or 'E' in value:
-                raise ValueError('scientific notation is not supported, use a string instead')
+                raise OrionisEnvironmentValueException('scientific notation is not supported, use a string instead')
             return value
+
         if isinstance(value, (list, dict)):
             return repr(value)
+
         if hasattr(value, '__dict__'):
-            raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
+            raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")
+
         if not isinstance(value, (list, dict, bool, int, float, str)):
-            raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
+            raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")
+
         if isinstance(value, (list, dict, bool, int, float, str)):
             if type(value).__module__ != "builtins" and not isinstance(value, str):
-                raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
+                raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")
             return repr(value) if not isinstance(value, str) else value
-        raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
+
+        raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")

orionis/services/environment/env.py

@@ -2,11 +2,19 @@ from orionis.services.environment.contracts.env import IEnv
 from orionis.services.environment.dot_env import DotEnv
 from typing import Any, Optional, Dict
 
-def env(key: str, default: Any = None) -> Any:
+def env(key: str, default: Any = None, is_path: bool = False) -> Any:
     """
-    Helper function to retrieve the value of an environment variable by key.
+    Retrieve the value of an environment variable by key.
+
+    Args:
+        key (str): The name of the environment variable to retrieve.
+        default (Any, optional): The value to return if the key is not found. Defaults to None.
+        is_path (bool, optional): If True, the value will be treated as a file path. Defaults to False.
+
+    Returns:
+        Any: The value of the environment variable if found, otherwise the default value.
     """
-    return DotEnv().get(key, default)
+    return DotEnv().get(key, default, is_path)
 
 class Env(IEnv):
     """
@@ -19,48 +27,88 @@ class Env(IEnv):
 
     @classmethod
     def _dotenv(cls) -> DotEnv:
+        """
+        Returns a singleton instance of the DotEnv class.
+
+        If the instance does not exist, it creates a new one and stores it in the class attribute.
+        Subsequent calls will return the same instance.
+
+        Returns:
+            DotEnv: The singleton instance of the DotEnv class.
+        """
         if cls._dotenv_instance is None:
             cls._dotenv_instance = DotEnv()
         return cls._dotenv_instance
 
     @staticmethod
-    def get(key: str, default: Any = None) -> Any:
+    def get(key: str, default: Any = None, is_path: bool = False) -> Any:
         """
-        Retrieve the value of an environment variable by key.
+        Retrieve the value of an environment variable.
+
+        Args:
+            key (str): The name of the environment variable to retrieve.
+            default (Any, optional): The value to return if the environment variable is not found. Defaults to None.
+            is_path (bool, optional): If True, treat the value as a filesystem path. Defaults to False.
+
+        Returns:
+            Any: The value of the environment variable if found, otherwise the default value.
         """
-        return Env._dotenv().get(key, default)
+        return Env._dotenv().get(key, default, is_path)
 
     @staticmethod
-    def set(key: str, value: str) -> bool:
+    def set(key: str, value: str, is_path: bool = False) -> bool:
         """
-        Sets the value of an environment variable.
+        Sets an environment variable with the specified key and value.
+
+        Args:
+            key (str): The name of the environment variable to set.
+            value (str): The value to assign to the environment variable.
+            is_path (bool, optional): If True, treats the value as a file system path. Defaults to False.
+
+        Returns:
+            bool: True if the environment variable was set successfully, False otherwise.
         """
-        return Env._dotenv().set(key, value)
+        return Env._dotenv().set(key, value, is_path)
 
     @staticmethod
     def unset(key: str) -> bool:
         """
         Removes the specified environment variable from the environment.
+
+        Args:
+            key (str): The name of the environment variable to remove.
+
+        Returns:
+            bool: True if the variable was successfully removed, False otherwise.
         """
         return Env._dotenv().unset(key)
 
     @staticmethod
     def all() -> Dict[str, Any]:
         """
-        Retrieve all environment variables from the DotEnv instance.
+        Retrieve all environment variables as a dictionary.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing all environment variables loaded by the dotenv configuration.
         """
         return Env._dotenv().all()
 
     @staticmethod
     def toJson() -> str:
         """
-        Serializes the current environment variables managed by the DotEnv instance to a JSON-formatted string.
+        Serializes the environment variables managed by the Env class into a JSON-formatted string.
+
+        Returns:
+            str: A JSON string representation of the environment variables.
         """
         return Env._dotenv().toJson()
 
     @staticmethod
     def toBase64() -> str:
         """
-        Converts the current environment variables to a Base64-encoded string.
+        Converts the environment variables loaded by the dotenv instance to a Base64-encoded string.
+
+        Returns:
+            str: The Base64-encoded representation of the environment variables.
         """
         return Env._dotenv().toBase64()

orionis/services/environment/exceptions/value_exception.py

@@ -0,0 +1,27 @@
+class OrionisEnvironmentValueException(Exception):
+    """
+    Exception raised for invalid or unexpected environment values within the Orionis framework.
+    This exception is intended to signal issues encountered when an environment variable,
+    configuration value, or similar parameter does not meet the expected criteria or format.
+    It provides a clear and descriptive error message to facilitate debugging and error handling.
+    Attributes:
+        raise OrionisEnvironmentValueException("Invalid value for ORIONIS_MODE: expected 'production' or 'development'.")
+        msg (str): The error message describing the specific value-related exception.
+    """
+
+    def __init__(self, msg: str):
+        """
+        Initializes the exception with a custom error message.
+        Args:
+            msg (str): The error message describing the exception.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the exception, including the class name and the first argument.
+
+        Returns:
+            str: A formatted string with the exception class name and its first argument.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"