orionis 0.213.1__py3-none-any.whl → 0.216.0__py3-none-any.whl

orionis/framework.py

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

orionis/luminate/console/output/console.py

@@ -4,7 +4,7 @@ import os
 import sys
 from orionis.luminate.console.output.styles import ANSIColors
 from orionis.luminate.contracts.console.output.console import IConsole
-from orionis.luminate.support.exception_parse import ExceptionParse
+from orionis.luminate.support.parsers.exception_parser import ExceptionParser
 
 class Console(IConsole):
     """
@@ -533,7 +533,7 @@ class Console(IConsole):
         This method prints the exception type, message, and a detailed stack trace.
         """
 
-        errors = ExceptionParse.toDict(e)
+        errors = ExceptionParser(e).toDict()
         error_type = str(errors.get("error_type")).split(".")[-1]
         error_message = str(errors.get("error_message")).replace(error_type, "").replace("[]", "").strip()
         stack_trace = errors.get("stack_trace")

orionis/luminate/support/inspection/contracts/reflection.py

@@ -0,0 +1,187 @@
+import abc
+from abc import ABC, abstractmethod
+from typing import Any, Type, TypeVar
+
+T = TypeVar('T')
+ABC = TypeVar('ABC', bound=abc.ABC)
+
+class IReflection(ABC):
+    """Interface for a static reflection factory class.
+
+    Defines the contract for creating various types of reflection objects
+    that encapsulate different aspects of Python's reflection capabilities.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def instance(instance: Any):
+        """Create a reflection object for a class instance.
+
+        Parameters
+        ----------
+        instance : Any
+            The instance to reflect upon
+
+        Returns
+        -------
+        ReflexionInstance
+            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__
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def instanceWithAbstract(instance: Any, abstract: Type[ABC]):
+        """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
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def abstract(abstract: Type[ABC]):
+        """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
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def concrete(concrete: Type[T]):
+        """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
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def concreteWithAbstract(concrete: Type[T], abstract: Type[ABC]):
+        """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 both classes
+
+        Raises
+        ------
+        TypeError
+            If either input is not a class
+        ValueError
+            If concrete is not instantiable or abstract is not actually abstract
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def module(module: str):
+        """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
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def moduleWithClassName(module: str, class_name: str):
+        """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 both 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
+        """
+        pass

orionis/luminate/support/inspection/contracts/reflexion_abstract.py

@@ -0,0 +1,265 @@
+import abc
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple, Type, TypeVar
+
+class IReflexionAbstract(ABC):
+    """Interface for abstract class reflection operations.
+
+    Defines the contract for inspecting and analyzing abstract classes,
+    including their methods, properties, inheritance, and metadata.
+    """
+
+    @abstractmethod
+    def getClassName(self) -> str:
+        """Get the name of the abstract class.
+
+        Returns
+        -------
+        str
+            The class name
+        """
+        pass
+
+    @abstractmethod
+    def getModuleName(self) -> str:
+        """Get the module name where the abstract class is defined.
+
+        Returns
+        -------
+        str
+            The module name
+        """
+        pass
+
+    @abstractmethod
+    def getAbstractMethods(self) -> Set[str]:
+        """Get names of all abstract methods required by the class.
+
+        Returns
+        -------
+        Set[str]
+            Set of abstract method names (excluding properties)
+        """
+        pass
+
+    @abstractmethod
+    def getAbstractProperties(self) -> Set[str]:
+        """Get names of all abstract properties required by the class.
+
+        Returns
+        -------
+        Set[str]
+            Set of abstract property names
+        """
+        pass
+
+    @abstractmethod
+    def getConcreteMethods(self) -> Dict[str, Callable]:
+        """Get all implemented concrete methods in the abstract class.
+
+        Returns
+        -------
+        Dict[str, Callable]
+            Dictionary mapping method names to their implementations
+        """
+        pass
+
+    @abstractmethod
+    def getStaticMethods(self) -> List[str]:
+        """Get names of all static methods in the class.
+
+        Returns
+        -------
+        List[str]
+            List of static method names
+        """
+        pass
+
+    @abstractmethod
+    def getClassMethods(self) -> List[str]:
+        """Get names of all class methods in the abstract class.
+
+        Returns
+        -------
+        List[str]
+            List of class method names
+        """
+        pass
+
+    @abstractmethod
+    def getProperties(self) -> List[str]:
+        """Get names of all properties in the abstract class.
+
+        Returns
+        -------
+        List[str]
+            List of property names
+        """
+        pass
+
+    @abstractmethod
+    def getMethodSignature(self, methodName: str) -> inspect.Signature:
+        """Get the signature of a specific method.
+
+        Parameters
+        ----------
+        methodName : str
+            Name of the method to inspect
+
+        Returns
+        -------
+        inspect.Signature
+            The method signature
+
+        Raises
+        ------
+        AttributeError
+            If the method doesn't exist
+        """
+        pass
+
+    @abstractmethod
+    def getPropertySignature(self, propertyName: str) -> inspect.Signature:
+        """Get the signature of a property's getter method.
+
+        Parameters
+        ----------
+        propertyName : str
+            Name of the property to inspect
+
+        Returns
+        -------
+        inspect.Signature
+            The getter signature
+
+        Raises
+        ------
+        AttributeError
+            If the property doesn't exist or has no getter
+        """
+        pass
+
+    @abstractmethod
+    def getDocstring(self) -> Optional[str]:
+        """Get the class docstring.
+
+        Returns
+        -------
+        Optional[str]
+            The docstring if available
+        """
+        pass
+
+    @abstractmethod
+    def getBaseAbstractClasses(self) -> Tuple[Type[ABC], ...]:
+        """Get direct abstract base classes.
+
+        Returns
+        -------
+        Tuple[Type[ABC], ...]
+            Tuple of abstract base classes
+        """
+        pass
+
+    @abstractmethod
+    def getInterfaceMethods(self) -> Dict[str, inspect.Signature]:
+        """Get all abstract methods with their signatures.
+
+        Returns
+        -------
+        Dict[str, inspect.Signature]
+            Dictionary mapping method names to their signatures
+        """
+        pass
+
+    @abstractmethod
+    def isSubclassOf(self, abstract_class: Type[ABC]) -> bool:
+        """Check inheritance relationship with another abstract class.
+
+        Parameters
+        ----------
+        abstract_class : Type[ABC]
+            The abstract class to check against
+
+        Returns
+        -------
+        bool
+            True if this class inherits from the given abstract class
+        """
+        pass
+
+    @abstractmethod
+    def getSourceCode(self) -> Optional[str]:
+        """Get the class source code.
+
+        Returns
+        -------
+        Optional[str]
+            The source code if available
+        """
+        pass
+
+    @abstractmethod
+    def getFileLocation(self) -> Optional[str]:
+        """Get the file where the class is defined.
+
+        Returns
+        -------
+        Optional[str]
+            File path if available
+        """
+        pass
+
+    @abstractmethod
+    def getAnnotations(self) -> Dict[str, Any]:
+        """Get type annotations for the class.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Dictionary of attribute annotations
+        """
+        pass
+
+    @abstractmethod
+    def getDecorators(self, method_name: str) -> List[str]:
+        """Get decorators applied to a specific method.
+
+        Parameters
+        ----------
+        method_name : str
+            Name of the method to inspect
+
+        Returns
+        -------
+        List[str]
+            List of decorator names
+        """
+        pass
+
+    @abstractmethod
+    def isProtocol(self) -> bool:
+        """Check if the class is a Protocol.
+
+        Returns
+        -------
+        bool
+            True if this is a Protocol class
+        """
+        pass
+
+    @abstractmethod
+    def getRequiredAttributes(self) -> Set[str]:
+        """For Protocol classes, get required attributes.
+
+        Returns
+        -------
+        Set[str]
+            Set of required attribute names
+
+        Notes
+        -----
+        Returns empty set for non-Protocol classes
+        """
+        pass

orionis/luminate/support/inspection/reflection.py

@@ -1,5 +1,6 @@
 import abc
 from typing import Any, Type, TypeVar
+from orionis.luminate.contracts.support.reflection import IReflection
 from orionis.luminate.support.inspection.functions import (
     _ensure_abstract_class,
     _ensure_instantiable_class,
@@ -18,7 +19,7 @@ from orionis.luminate.support.inspection.reflexion_module_with_classname import
 T = TypeVar('T')
 ABC = TypeVar('ABC', bound=abc.ABC)
 
-class Reflection:
+class Reflection(IReflection):
     """A static class providing factory methods for creating reflection objects.
 
     This class provides methods to create various types of reflection objects

orionis/luminate/support/inspection/reflexion_abstract.py

@@ -3,10 +3,11 @@ import ast
 import inspect
 import types
 from typing import Any, Callable, Dict, List, Optional, Set, Tuple, Type, TypeVar
+from orionis.luminate.support.inspection.contracts.reflexion_abstract import IReflexionAbstract
 
 ABC = TypeVar('ABC', bound=abc.ABC)
 
-class ReflexionAbstract:
+class ReflexionAbstract(IReflexionAbstract):
     """A reflection object encapsulating an abstract class.
 
     Parameters

orionis/luminate/support/parsers/contracts/exception_parser.py

@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+class IExceptionParser(ABC):
+    """
+    Abstract base interface for classes that parse exceptions
+    into a structured dictionary format.
+    """
+
+    @property
+    @abstractmethod
+    def raw_exception(self) -> Exception:
+        """
+        Get the original exception object.
+
+        Returns
+        -------
+        Exception
+            The raw exception instance.
+        """
+        pass
+
+    @abstractmethod
+    def toDict(self) -> Dict[str, Any]:
+        """
+        Serialize the exception into a dictionary.
+
+        Returns
+        -------
+        dict
+            A structured representation of the exception including details such as:
+            - error_type
+            - error_message
+            - error_code
+            - stack_trace
+            - cause (if any)
+        """
+        pass

orionis/luminate/support/parsers/exception_parser.py

@@ -0,0 +1,107 @@
+import traceback
+from typing import Any, Dict, List, Optional, Union
+from orionis.luminate.support.parsers.contracts.exception_parser import IExceptionParser
+
+class ExceptionParser(IExceptionParser):
+    """
+    A utility class to parse an exception and convert it into a structured dictionary.
+    """
+
+    def __init__(self, exception: Exception) -> None:
+        """
+        Initialize the ExceptionParser with the given exception.
+
+        Parameters
+        ----------
+        exception : Exception
+            The exception to be parsed.
+        """
+        self.__exception = exception
+
+    @property
+    def raw_exception(self) -> Exception:
+        """
+        Get the original exception object.
+
+        Returns
+        -------
+        Exception
+            The raw exception instance.
+        """
+        return self.__exception
+
+    def toDict(self) -> Dict[str, Any]:
+        """
+        Serialize the exception into a dictionary format.
+
+        Returns
+        -------
+        dict
+            A dictionary containing:
+            - 'error_type': The type of exception.
+            - 'error_message': The complete traceback string.
+            - 'error_code': Custom error code, if available.
+            - 'stack_trace': A list of frames in the stack trace, each with:
+                - 'filename': File where the error occurred.
+                - 'lineno': Line number.
+                - 'name': Function or method name.
+                - 'line': The source line of code.
+            - 'cause': A nested dictionary representing the original cause (if any).
+        """
+        tb = traceback.TracebackException.from_exception(self.__exception, capture_locals=False)
+
+        return {
+            "error_type": tb.exc_type.__name__ if tb.exc_type else "Unknown",
+            "error_message": str(tb).strip(),
+            "error_code": getattr(self.__exception, "code", None),
+            "stack_trace": self.__parse_stack(tb.stack),
+            "cause": self.__parse_cause(self.__exception.__cause__) if self.__exception.__cause__ else None
+        }
+
+    def __parse_stack(self, stack: traceback.StackSummary) -> List[Dict[str, Union[str, int, None]]]:
+        """
+        Helper method to parse the stack trace.
+
+        Parameters
+        ----------
+        stack : traceback.StackSummary
+            The summary of the stack.
+
+        Returns
+        -------
+        list of dict
+            A list of dictionaries with detailed frame information.
+        """
+        return [
+            {
+                "filename": frame.filename,
+                "lineno": frame.lineno,
+                "name": frame.name,
+                "line": frame.line
+            }
+            for frame in stack
+        ]
+
+    def __parse_cause(self, cause: Optional[BaseException]) -> Optional[Dict[str, Any]]:
+        """
+        Recursively parse the cause of an exception, if available.
+
+        Parameters
+        ----------
+        cause : BaseException or None
+            The original cause of the exception.
+
+        Returns
+        -------
+        dict or None
+            A dictionary with the cause information or None if no cause exists.
+        """
+        if not isinstance(cause, BaseException):
+            return None
+
+        cause_tb = traceback.TracebackException.from_exception(cause)
+        return {
+            "error_type": cause_tb.exc_type.__name__ if cause_tb.exc_type else "Unknown",
+            "error_message": str(cause_tb).strip(),
+            "stack_trace": self.__parse_stack(cause_tb.stack)
+        }