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

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.")

orionis/services/introspection/reflection.py

@@ -0,0 +1,216 @@
+import abc
+from typing import Any, Type, TypeVar
+from orionis._contracts.support.reflection import IReflection
+from orionis.support.introspection.helpers.functions import HelpersReflection
+from orionis.support.introspection.abstracts.reflect_abstract import ReflexionAbstract
+from orionis.support.introspection.reflexion_concrete import ReflexionConcrete
+from orionis.support.introspection.reflexion_concrete_with_abstract import ReflexionConcreteWithAbstract
+from orionis.support.introspection.instances.reflection_instance import ReflectionInstance
+from orionis.support.introspection.reflexion_instance_with_abstract import ReflexionInstanceWithAbstract
+from orionis.support.introspection.reflexion_module import ReflexionModule
+from orionis.support.introspection.reflexion_module_with_classname import ReflexionModuleWithClassName
+
+T = TypeVar('T')
+ABC = TypeVar('ABC', bound=abc.ABC)
+
+class Reflection(IReflection):
+    """A static class providing factory methods for creating reflection objects.
+
+    This class provides methods to create various types of reflection objects
+    that encapsulate different aspects of Python's reflection capabilities.
+    Each method validates its inputs before creating the appropriate reflection object.
+
+    Methods
+    -------
+    instance(instance: Any) -> ReflexionInstance
+        Creates a reflection object for a class instance
+    instanceWithAbstract(instance: Any, abstract: Type[ABC]) -> ReflexionInstanceWithAbstract
+        Creates a reflection object for a class instance with its abstract parent
+    abstract(abstract: Type[ABC]) -> ReflexionAbstract
+        Creates a reflection object for an abstract class
+    concrete(concrete: Type[T]) -> ReflexionConcrete
+        Creates a reflection object for a concrete class
+    concreteWithAbstract(concrete: Type[T], abstract: Type[ABC]) -> ReflexionConcreteWithAbstract
+        Creates a reflection object for a concrete class with its abstract parent
+    module(module: str) -> ReflexionModule
+        Creates a reflection object for a module
+    moduleWithClassName(module: str, class_name: str) -> ReflexionModuleWithClassName
+        Creates a reflection object for a module with a specific class name
+    """
+
+    @staticmethod
+    def instance(instance: Any) -> 'ReflectionInstance':
+        """Create a reflection object for a class instance.
+
+        Parameters
+        ----------
+        instance : Any
+            The instance to reflect upon
+
+        Returns
+        -------
+        ReflectionInstance
+            A reflection object encapsulating the instance
+
+        Raises
+        ------
+        TypeError
+            If the input is not an object instance
+        ValueError
+            If the instance is from builtins, abc, or __main__
+        """
+        HelpersReflection.ensureUserDefinedClassInstance(instance)
+        return ReflectionInstance(instance)
+
+    @staticmethod
+    def instanceWithAbstract(instance: Any, abstract: Type[ABC]) -> 'ReflexionInstanceWithAbstract':
+        """Create a reflection object for a class instance with its abstract parent.
+
+        Parameters
+        ----------
+        instance : Any
+            The instance to reflect upon
+        abstract : Type[ABC]
+            The abstract parent class
+
+        Returns
+        -------
+        ReflexionInstanceWithAbstract
+            A reflection object encapsulating the instance and its abstract parent
+
+        Raises
+        ------
+        TypeError
+            If the instance is not an object or abstract is not a class
+        ValueError
+            If the instance is invalid or abstract is not actually abstract
+        """
+        HelpersReflection.ensureUserDefinedClassInstance(instance)
+        HelpersReflection.ensureAbstractClass(abstract)
+        return ReflexionInstanceWithAbstract(instance, abstract)
+
+    @staticmethod
+    def abstract(abstract: Type[ABC]) -> 'ReflexionAbstract':
+        """Create a reflection object for an abstract class.
+
+        Parameters
+        ----------
+        abstract : Type[ABC]
+            The abstract class to reflect upon
+
+        Returns
+        -------
+        ReflexionAbstract
+            A reflection object encapsulating the abstract class
+
+        Raises
+        ------
+        TypeError
+            If the input is not a class
+        ValueError
+            If the class is not abstract
+        """
+        HelpersReflection.ensureAbstractClass(abstract)
+        return ReflexionAbstract(abstract)
+
+    @staticmethod
+    def concrete(concrete: Type[T]) -> 'ReflexionConcrete':
+        """Create a reflection object for a concrete class.
+
+        Parameters
+        ----------
+        concrete : Type[T]
+            The concrete class to reflect upon
+
+        Returns
+        -------
+        ReflexionConcrete
+            A reflection object encapsulating the concrete class
+
+        Raises
+        ------
+        TypeError
+            If the input is not a class
+        ValueError
+            If the class is abstract or cannot be instantiated
+        """
+        HelpersReflection.ensureInstantiableClass(concrete)
+        return ReflexionConcrete(concrete)
+
+    @staticmethod
+    def concreteWithAbstract(concrete: Type[T], abstract: Type[ABC]) -> 'ReflexionConcreteWithAbstract':
+        """Create a reflection object for a concrete class with its abstract parent.
+
+        Parameters
+        ----------
+        concrete : Type[T]
+            The concrete class to reflect upon
+        abstract : Type[ABC]
+            The abstract parent class
+
+        Returns
+        -------
+        ReflexionConcreteWithAbstract
+            A reflection object encapsulating the concrete class and its abstract parent
+
+        Raises
+        ------
+        TypeError
+            If either input is not a class
+        ValueError
+            If concrete is not instantiable or abstract is not actually abstract
+        """
+        HelpersReflection.ensureInstantiableClass(concrete)
+        HelpersReflection.ensureAbstractClass(abstract)
+        return ReflexionConcreteWithAbstract(concrete, abstract)
+
+    @staticmethod
+    def module(module: str) -> 'ReflexionModule':
+        """Create a reflection object for a module.
+
+        Parameters
+        ----------
+        module : str
+            The module name to reflect upon
+
+        Returns
+        -------
+        ReflexionModule
+            A reflection object encapsulating the module
+
+        Raises
+        ------
+        TypeError
+            If the input is not a string
+        ValueError
+            If the module cannot be imported
+        """
+        HelpersReflection.ensureValidModule(module)
+        return ReflexionModule(module)
+
+    @staticmethod
+    def moduleWithClassName(module: str, class_name: str) -> 'ReflexionModuleWithClassName':
+        """Create a reflection object for a module with a specific class name.
+
+        Parameters
+        ----------
+        module : str
+            The module name to reflect upon
+        class_name : str
+            The class name to look for in the module
+
+        Returns
+        -------
+        ReflexionModuleWithClassName
+            A reflection object encapsulating the module and class name
+
+        Raises
+        ------
+        TypeError
+            If either input is not a string
+        ValueError
+            If the module cannot be imported or the class doesn't exist in it
+        """
+        HelpersReflection.ensureValidModule(module)
+        HelpersReflection.ensureValidClassName(class_name)
+        return ReflexionModuleWithClassName(module, class_name)

orionis/services/parsers/serializer.py

@@ -1,4 +1,4 @@
-from orionis.services.parsers.exception import ExceptionParser
+from orionis.services.parsers.exceptions.exception_parser import ExceptionParser
 
 class Parser:
 

orionis/services/paths/exceptions/not_found_exceptions.py

@@ -0,0 +1,28 @@
+class OrionisFileNotFoundException(Exception):
+    """
+    Exception raised when a file is not found in the Orionis framework.
+
+    Args:
+        msg (str): A detailed message describing the missing file.
+
+    Example:
+        raise OrionisFileNotFoundException("File 'config.yaml' not found.")
+    """
+
+    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 the first argument.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/services/paths/exceptions/path_value_exceptions.py

@@ -0,0 +1,28 @@
+class OrionisPathValueException(Exception):
+    """
+    Exception raised when a file is not found in the Orionis framework.
+
+    Args:
+        msg (str): A detailed message describing the missing file.
+
+    Example:
+        raise OrionisFileNotFoundException("File 'config.yaml' not found.")
+    """
+
+    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 the first argument.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/services/paths/resolver.py

@@ -1,6 +1,8 @@
 import os
 from pathlib import Path
 from orionis.services.paths.contracts.resolver import IResolver
+from orionis.services.paths.exceptions.not_found_exceptions import OrionisFileNotFoundException
+from orionis.services.paths.exceptions.path_value_exceptions import OrionisPathValueException
 
 class Resolver(IResolver):
     """
@@ -38,9 +40,9 @@ class Resolver(IResolver):
 
         Raises
         ------
-        FileNotFoundError
+        OrionisFileNotFoundException
             If the resolved path does not exist.
-        ValueError
+        OrionisPathValueException
             If the resolved path is neither a valid directory nor a file.
         """
         # Combine the base path with the relative path and resolve it
@@ -48,11 +50,11 @@ class Resolver(IResolver):
 
         # Validate that the path exists
         if not resolved_path.exists():
-            raise FileNotFoundError(f"The requested path does not exist: {resolved_path}")
+            raise OrionisFileNotFoundException(f"The requested path does not exist: {resolved_path}")
 
         # Validate that the path is either a directory or a file
         if not (resolved_path.is_dir() or resolved_path.is_file()):
-            raise ValueError(f"The requested path is neither a valid directory nor a file: {resolved_path}")
+            raise OrionisPathValueException(f"The requested path is neither a valid directory nor a file: {resolved_path}")
 
         # Store the resolved path in the instance variable
         self.resolved_path = resolved_path

orionis/services/standard/exceptions/path_value_exceptions.py

@@ -0,0 +1,28 @@
+class OrionisStdValueException(Exception):
+    """
+    Exception raised for standard value errors in the Orionis framework.
+
+    Args:
+        msg (str): A detailed message describing the value error.
+
+    Example:
+        raise OrionisStdValueException("Invalid value for parameter 'timeout'.")
+    """
+
+    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 the first argument.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/services/standard/std.py

@@ -1,4 +1,5 @@
 from orionis.services.standard.contracts.std import IStdClass
+from orionis.services.standard.exceptions.path_value_exceptions import OrionisStdValueException
 
 class StdClass(IStdClass):
     """
@@ -81,14 +82,14 @@ class StdClass(IStdClass):
 
         Raises
         ------
-        ValueError
+        OrionisStdValueException
             If an attribute name is invalid or conflicts with existing methods.
         """
         for key, value in kwargs.items():
             if key.startswith('__') and key.endswith('__'):
-                raise ValueError(f"Cannot set attribute with reserved name: {key}")
+                raise OrionisStdValueException(f"Cannot set attribute with reserved name: {key}")
             if hasattr(self.__class__, key):
-                raise ValueError(f"Cannot set attribute '{key}' as it conflicts with a class method")
+                raise OrionisStdValueException(f"Cannot set attribute '{key}' as it conflicts with a class method")
             setattr(self, key, value)
 
     def remove(self, *attributes):

orionis/test/entities/test_result.py

@@ -5,9 +5,22 @@ from orionis.test.enums.test_status import TestStatus
 @dataclass(frozen=True, kw_only=True)
 class TestResult:
     """
-    Represents the result of a test execution.
+    Represents the result of a test execution, including status, timing, and error details.
+    Attributes:
+        id (Any): Unique identifier for the test result.
+        name (str): Name of the test.
+        status (TestStatus): Status of the test execution (e.g., passed, failed).
+        execution_time (float): Time taken to execute the test, in seconds.
+        error_message (Optional[str]): Error message if the test failed, otherwise None.
+        traceback (Optional[str]): Traceback information if an error occurred, otherwise None.
+        class_name (Optional[str]): Name of the class containing the test, if applicable.
+        method (Optional[str]): Name of the method representing the test, if applicable.
+        module (Optional[str]): Name of the module containing the test, if applicable.
+        file_path (Optional[str]): Path to the file containing the test, if applicable.
+        doc_string (Optional[str]): Docstring of the test, if applicable.
     """
 
+
     id: Any = field(
         metadata={
             "description": "Unique identifier for the test result."