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

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.283.0"
+VERSION = "0.285.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):
     """
@@ -206,8 +207,7 @@ class DotEnv(metaclass=Singleton):
             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("\\", "/")
@@ -227,21 +227,21 @@ class DotEnv(metaclass=Singleton):
         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,6 +27,15 @@ 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
@@ -26,14 +43,30 @@ class Env(IEnv):
     @staticmethod
     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, is_path)
 
     @staticmethod
     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, is_path)
 
@@ -41,26 +74,41 @@ class Env(IEnv):
     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]}"

orionis/services/introspection/helpers/functions.py

@@ -0,0 +1,285 @@
+import importlib
+import inspect
+from typing import Any, Type
+
+class HelpersReflection:
+    """
+    A collection of helper functions for reflection and inspection.
+    """
+
+    @staticmethod
+    def isValidModule(module_name: str) -> bool:
+        """Check if a module name is valid and can be imported.
+
+        Parameters
+        ----------
+        module_name : str
+            The name of the module to check
+
+        Returns
+        -------
+        bool
+            True if the module is valid and can be imported, False otherwise
+        """
+        try:
+            importlib.import_module(module_name)
+            return True
+        except ImportError:
+            return False
+
+    @staticmethod
+    def ensureValidModule(module_name: str) -> None:
+        """Ensure a module name is valid and can be imported.
+
+        Parameters
+        ----------
+        module_name : str
+            The name of the module to check
+
+        Raises
+        ------
+        ValueError
+            If the module cannot be imported or is invalid
+        """
+        if not isinstance(module_name, str):
+            raise TypeError(f"Module name must be a string, got {type(module_name)}")
+        if not HelpersReflection.isValidModule(module_name):
+            raise ValueError(f"Invalid or non-importable module: {module_name}")
+
+    @staticmethod
+    def isInstantiableClass(cls: Type) -> bool:
+        """Check if a class is concrete and can be instantiated.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to check
+
+        Returns
+        --
+        bool
+            True if the class is concrete and can be instantiated, False otherwise
+        """
+        if not isinstance(cls, type):
+            return False
+        if HelpersReflection.isAbstractClass(cls):
+            return False
+
+        # Try to create an instance to verify it's truly concrete
+        try:
+            cls()
+            return True
+        except TypeError:
+            return False
+
+    @staticmethod
+    def ensureNotBuiltinType(cls: Type) -> None:
+        """Ensure a class is not a built-in or primitive type.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to check
+
+        Raises
+        ------
+        TypeError
+            If the input is not a class
+        ValueError
+            If the class is a built-in or primitive type
+        """
+        if not isinstance(cls, type):
+            raise TypeError(f"Expected a class, got {type(cls)}")
+
+        builtin_types = {
+            int, float, str, bool, bytes, type(None), complex,
+            list, tuple, dict, set, frozenset
+        }
+
+        if cls in builtin_types:
+            raise ValueError(f"Class '{cls.__name__}' is a built-in or primitive type and cannot be used.")
+
+    @staticmethod
+    def ensureInstantiableClass(cls: Type) -> None:
+        """Ensure a class is concrete and can be instantiated.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to check
+
+        Raises
+        ------
+        TypeError
+            If the input is not a class
+        ValueError
+            If the class is abstract or cannot be instantiated
+        """
+        if HelpersReflection.ensureNotBuiltinType(cls):
+            raise TypeError(f"Invalid class: {cls!r}")
+
+        if not isinstance(cls, type):
+            raise TypeError(f"Expected a class, got {type(cls)}")
+
+        if HelpersReflection.isAbstractClass(cls):
+            raise ValueError(f"Class '{cls.__name__}' is abstract")
+
+        try:
+            cls()
+        except TypeError as e:
+            raise ValueError(f"Class '{cls.__name__}' cannot be instantiated: {str(e)}")
+
+    @staticmethod
+    def isValidClassName(module_name: str, class_name: str) -> bool:
+        """Check if a class exists in a given module.
+
+        Parameters
+        ----------
+        module_name : str
+            The name of the module to check
+        class_name : str
+            The name of the class to look for
+
+        Returns
+        -------
+        bool
+            True if the class exists in the module, False otherwise
+        """
+        try:
+            module = importlib.import_module(module_name)
+            return hasattr(module, class_name) and inspect.isclass(getattr(module, class_name))
+        except ImportError:
+            return False
+
+    @staticmethod
+    def ensureValidClassName(module_name: str, class_name: str) -> None:
+        """Ensure a class exists in a given module.
+
+        Parameters
+        ----------
+        module_name : str
+            The name of the module to check
+        class_name : str
+            The name of the class to look for
+
+        Raises
+        ------
+        ValueError
+            If the class doesn't exist in the module
+        """
+        if not HelpersReflection.isValidClassName(module_name, class_name):
+            raise ValueError(f"Class '{class_name}' not found in module '{module_name}'")
+
+    @staticmethod
+    def isUserDefinedClassInstance(instance: Any) -> bool:
+        """Check if an object is an instance of a user-defined class.
+
+        Parameters
+        ----------
+        instance : Any
+            The object to check
+
+        Returns
+        -------
+        bool
+            True if the object is an instance of a user-defined class, False otherwise
+        """
+        return isinstance(instance, object) and type(instance).__module__ not in {'builtins', 'abc', '__main__'}
+
+    @staticmethod
+    def ensureUserDefinedClassInstance(instance: Any) -> None:
+        """Ensure an object is an instance of a user-defined class.
+
+        Parameters
+        ----------
+        instance : Any
+            The object to check
+
+        Raises
+        ------
+        TypeError
+            If the input is not an object instance
+        ValueError
+            If the instance is from builtins, abc, or __main__
+        """
+        if not isinstance(instance, object):
+            raise TypeError(f"Invalid object: {instance!r}")
+        module = type(instance).__module__
+        if module in {'builtins', 'abc'}:
+            raise ValueError(f"'{instance!r}' is not a user-defined class instance, belongs to '{module}'.")
+        if module == '__main__':
+            raise ValueError("Instance originates from '__main__', origin indeterminate.")
+
+    @staticmethod
+    def isAbstractClass(cls: Type) -> bool:
+        """Check if a class is abstract.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to check
+
+        Returns
+        -------
+        bool
+            True if the class is abstract, False otherwise
+        """
+        return isinstance(cls, type) and bool(getattr(cls, '__abstractmethods__', False))
+
+    @staticmethod
+    def ensureAbstractClass(cls: Type) -> None:
+        """Ensure a class is abstract.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to check
+
+        Raises
+        ------
+        TypeError
+            If the input is not a class
+        ValueError
+            If the class is not abstract
+        """
+        if not isinstance(cls, type):
+            raise TypeError(f"Invalid class: {cls!r}")
+        if not HelpersReflection.isAbstractClass(cls):
+            raise ValueError(f"Class '{cls.__name__}' is not abstract.")
+
+    @staticmethod
+    def isConcreteClass(cls: Type) -> bool:
+        """Check if a class is concrete.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to check
+
+        Returns
+        -------
+        bool
+            True if the class is concrete, False otherwise
+        """
+        return isinstance(cls, type) and not HelpersReflection.isAbstractClass(cls)
+
+    @staticmethod
+    def ensureConcreteClass(cls: Type) -> None:
+        """Ensure a class is concrete.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to check
+
+        Raises
+        ------
+        TypeError
+            If the input is not a class
+        ValueError
+            If the class is not concrete
+        """
+        if not isinstance(cls, type):
+            raise TypeError(f"Invalid class: {cls!r}")
+        if not HelpersReflection.isConcreteClass(cls):
+            raise ValueError(f"Class '{cls.__name__}' is not concrete.")