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

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

orionis/test/exceptions/test_persistence_error.py

@@ -0,0 +1,34 @@
+class OrionisTestPersistenceError(Exception):
+    """
+    Custom exception for persistence errors in tests within the Orionis framework.
+
+    This exception is used to indicate issues related to data persistence during test execution,
+    providing a descriptive message to help identify and resolve the error.
+
+    Args:
+        msg (str): A descriptive message explaining the cause of the persistence error.
+
+    Example:
+        raise OrionisTestPersistenceError("Failed to save test state to the database.")
+    """
+
+    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.
+        """
+        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.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/test/exceptions/test_runtime_error.py

@@ -0,0 +1,26 @@
+class OrionisTestRuntimeError(Exception):
+    """
+    Exception raised for errors that occur during the runtime of Orionis tests.
+    This exception is intended to provide a clear and descriptive error message
+    when a runtime error is encountered in the Orionis testing framework.
+    Attributes:
+    Example:
+        raise OrionisTestRuntimeError("An unexpected runtime error occurred during testing.")
+    """
+
+    def __init__(self, msg: str):
+        """
+        Initializes the exception with a given error message.
+        Args:
+            msg (str): The error message describing the runtime error.
+        """
+        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 string in the format '<ClassName>: <first argument>'.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/test/exceptions/test_value_error.py

@@ -0,0 +1,26 @@
+class OrionisTestValueError(Exception):
+    """
+    Custom exception class for handling value errors in the Orionis test framework.
+    This exception should be raised when a value-related error occurs during testing.
+    It provides a formatted string representation that includes the class name and the error message.
+    Example:
+        raise OrionisTestValueError("Invalid value provided.")
+    """
+
+    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 in the form 'ClassName: message'.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/test/logs/contracts/history.py

@@ -1,81 +1,54 @@
 from abc import ABC, abstractmethod
-from typing import Dict, List, Tuple
+from typing import Dict, List, Optional, Tuple
 
 class ITestHistory(ABC):
 
     @abstractmethod
-    def createTableIfNotExists(self) -> None:
+    def create(self, report: Dict) -> bool:
         """
-        Create the 'reportes' table if it does not already exist.
-
-        The table includes fields for the full JSON report and individual
-        statistics for querying and filtering.
-
-        Raises
-        ------
-        RuntimeError
-            If table creation fails due to a database error.
-        """
-        pass
-
-    @abstractmethod
-    def insertReport(self, report: Dict) -> None:
-        """
-        Insert a test report into the database.
+        Create a new test report in the history database.
 
         Parameters
         ----------
-        report : dict
-            Dictionary containing test statistics and metadata.
-
-            Required keys:
-                - total_tests : int
-                - passed : int
-                - failed : int
-                - errors : int
-                - skipped : int
-                - total_time : float
-                - success_rate : float
-                - timestamp : str (ISO format)
+        report : Dict
+            A dictionary containing the test report data.
 
-        Raises
-        ------
-        ValueError
-            If required keys are missing from the report.
-        RuntimeError
-            If insertion into the database fails.
+        Returns
+        -------
+        bool
+            True if the report was successfully created, False otherwise.
         """
         pass
 
-    def getReports(self) -> List[Tuple]:
+    def reset(self) -> bool:
         """
-        Retrieve all test reports from the database.
+        Reset the history database by dropping the existing table.
 
         Returns
         -------
-        List[Tuple]
-            A list of tuples representing each row in the `reportes` table.
-
-        Raises
-        ------
-        RuntimeError
-            If retrieval fails due to a database error.
+        bool
+            True if the database was successfully reset, False otherwise.
         """
         pass
 
-    def resetDatabase(self) -> None:
+    def get(
+        self,
+        first: Optional[int] = None,
+        last: Optional[int] = None
+    ) -> List[Tuple]:
         """
-        Drop the `reportes` table, effectively clearing the report history.
+        Retrieve test reports from the history database.
 
-        Raises
-        ------
-        RuntimeError
-            If table deletion fails.
-        """
-        pass
+        Parameters
+        ----------
+        first : Optional[int], default=None
+            The number of earliest reports to retrieve, ordered ascending by ID.
+        last : Optional[int], default=None
+            The number of latest reports to retrieve, ordered descending by ID.
 
-    def close(self) -> None:
-        """
-        Close the SQLite database connection gracefully.
+        Returns
+        -------
+        List[Tuple]
+            A list of tuples representing the retrieved reports.
         """
         pass