orionis 0.233.0__py3-none-any.whl → 0.235.0__py3-none-any.whl

orionis/framework.py

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

orionis/luminate/support/introspection/__init__.py

@@ -0,0 +1,7 @@
+from orionis.luminate.support.introspection.reflection import Reflection
+from orionis.luminate.support.introspection.reflection_instance import ReflectionInstance
+
+__all__ = [
+    "Reflection",
+    "ReflectionInstance",
+]

orionis/luminate/support/introspection/dependencies/contracts/reflect_dependencies.py

@@ -0,0 +1,43 @@
+from abc import ABC, abstractmethod
+from orionis.luminate.support.introspection.dependencies.entities.class_dependencies import ClassDependency
+from orionis.luminate.support.introspection.dependencies.entities.method_dependencies import MethodDependency
+
+class IReflectDependencies(ABC):
+    """
+    This class is used to reflect dependencies of a given object.
+    """
+
+    def __init__(self, obj):
+        self.__obj = obj
+
+    @abstractmethod
+    def getConstructorDependencies(self) -> ClassDependency:
+        """
+        Get the resolved and unresolved dependencies from the constructor of the instance's class.
+
+        Returns
+        -------
+        ClassDependency
+            A structured representation of the constructor dependencies, containing:
+            - resolved: Dictionary of resolved dependencies with their names and values.
+            - unresolved: List of unresolved dependencies (parameter names without default values or annotations).
+        """
+        pass
+
+    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+        """
+        Get the resolved and unresolved dependencies from a method of the instance's class.
+
+        Parameters
+        ----------
+        method_name : str
+            The name of the method to inspect
+
+        Returns
+        -------
+        MethodDependency
+            A structured representation of the method dependencies, containing:
+            - resolved: Dictionary of resolved dependencies with their names and values.
+            - unresolved: List of unresolved dependencies (parameter names without default values or annotations).
+        """
+        pass

orionis/luminate/support/introspection/dependencies/entities/class_dependencies.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List
+
+@dataclass(frozen=True)
+class ClassDependency:
+    """
+    A class to represent a dependency of a class instance.
+    """
+    resolved: Dict[str, Any]
+    unresolved: List[str]

orionis/luminate/support/introspection/dependencies/entities/method_dependencies.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List
+
+@dataclass(frozen=True)
+class MethodDependency:
+    """
+    A class to represent a method dependency of a class instance.
+    """
+    resolved: Dict[str, Any]
+    unresolved: List[str]

orionis/luminate/support/introspection/dependencies/entities/resolved_dependencies.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Type
+
+@dataclass(frozen=True)
+class ResolvedDependency:
+    """
+    A class to represent a resolved dependency of a class instance.
+    """
+    module_name: str
+    class_name: str
+    type: Type
+    full_class_path: str

orionis/luminate/support/introspection/dependencies/reflect_dependencies.py

@@ -0,0 +1,176 @@
+import inspect
+from typing import Any, Dict, List
+from orionis.luminate.support.introspection.dependencies.contracts.reflect_dependencies import IReflectDependencies
+from orionis.luminate.support.introspection.dependencies.entities.class_dependencies import ClassDependency
+from orionis.luminate.support.introspection.dependencies.entities.method_dependencies import MethodDependency
+from orionis.luminate.support.introspection.dependencies.entities.resolved_dependencies import ResolvedDependency
+
+class ReflectDependencies(IReflectDependencies):
+    """
+    This class is used to reflect dependencies of a given object.
+    """
+
+    def __init__(self, obj):
+        """
+        Initializes the ReflectDependencies instance with the given object.
+
+        Parameters
+        ----------
+        obj : Any
+            The object whose dependencies are to be reflected.
+        """
+        self.__obj = obj
+
+    def __paramSkip(self, param_name: str, param: inspect.Parameter) -> bool:
+        """
+        Determines whether a parameter should be skipped during dependency inspection.
+
+        Parameters
+        ----------
+        param_name : str
+            The name of the parameter.
+        param : inspect.Parameter
+            The parameter object to inspect.
+
+        Returns
+        -------
+        bool
+            True if the parameter should be skipped, False otherwise.
+        """
+        # Skip common parameters like 'self', 'cls', or special argument names
+        if param_name in {'self', 'cls', 'args', 'kwargs'}:
+            return True
+
+        # Skip 'self' in class methods or instance methods
+        if param_name == 'self' and isinstance(self.__obj, type):
+            return True
+
+        # Skip special parameters like *args and **kwargs
+        if param.kind in {param.VAR_POSITIONAL, param.VAR_KEYWORD}:
+            return True
+
+        return False
+
+    def __inspectSignature(self, target) -> inspect.Signature:
+        """
+        Safely retrieves the signature of a given target.
+
+        Parameters
+        ----------
+        target : Any
+            The target object (function, method, or callable) to inspect.
+
+        Returns
+        -------
+        inspect.Signature
+            The signature of the target.
+
+        Raises
+        ------
+        ValueError
+            If the signature cannot be inspected.
+        """
+        if not callable(target):
+            raise ValueError(f"Target {target} is not callable and cannot have a signature.")
+
+        try:
+            return inspect.signature(target)
+        except (ValueError, TypeError) as e:
+            raise ValueError(f"Unable to inspect signature of {target}: {str(e)}")
+
+    def getConstructorDependencies(self) -> ClassDependency:
+        """
+        Get the resolved and unresolved dependencies from the constructor of the instance's class.
+
+        Returns
+        -------
+        ClassDependency
+            A structured representation of the constructor dependencies, containing:
+            - resolved: Dictionary of resolved dependencies with their names and values.
+            - unresolved: List of unresolved dependencies (parameter names without default values or annotations).
+        """
+        signature = self.__inspectSignature(self.__obj.__init__)
+        resolved_dependencies: Dict[str, Any] = {}
+        unresolved_dependencies: List[str] = []
+
+        for param_name, param in signature.parameters.items():
+
+            # Skip parameters that are not relevant for dependency resolution
+            if self.__paramSkip(param_name, param):
+                continue
+
+            # Add to the list of unresolved dependencies if it has no default value or annotation
+            if param.annotation is param.empty and param.default is param.empty:
+                unresolved_dependencies.append(param_name)
+                continue
+
+            # Parameters with default values
+            if param.default is not param.empty:
+                resolved_dependencies[param_name] = param.default
+                continue
+
+            # If the parameter has an annotation, it is added to the list of resolved dependencies
+            if param.annotation is not param.empty:
+                module_path = param.annotation.__module__
+                resolved_dependencies[param_name] = ResolvedDependency(
+                    module_name=module_path,
+                    class_name=param.annotation.__name__,
+                    type=param.annotation,
+                    full_class_path=f"{module_path}.{param.annotation.__name__}"
+                )
+
+        return ClassDependency(
+            resolved=resolved_dependencies,
+            unresolved=unresolved_dependencies
+        )
+
+    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+        """
+        Get the resolved and unresolved dependencies from a method of the instance's class.
+
+        Parameters
+        ----------
+        method_name : str
+            The name of the method to inspect
+
+        Returns
+        -------
+        MethodDependency
+            A structured representation of the method dependencies, containing:
+            - resolved: Dictionary of resolved dependencies with their names and values.
+            - unresolved: List of unresolved dependencies (parameter names without default values or annotations).
+        """
+        signature = self.__inspectSignature(getattr(self.__obj, method_name))
+        resolved_dependencies: Dict[str, Any] = {}
+        unresolved_dependencies: List[str] = []
+
+        for param_name, param in signature.parameters.items():
+
+            # Skip parameters that are not relevant for dependency resolution
+            if self.__paramSkip(param_name, param):
+                continue
+
+            # Add to the list of unresolved dependencies if it has no default value or annotation
+            if param.annotation is param.empty and param.default is param.empty:
+                unresolved_dependencies.append(param_name)
+                continue
+
+            # Parameters with default values
+            if param.default is not param.empty:
+                resolved_dependencies[param_name] = param.default
+                continue
+
+            # If the parameter has an annotation, it is added to the list of resolved dependencies
+            if param.annotation is not param.empty:
+                module_path = param.annotation.__module__
+                resolved_dependencies[param_name] = ResolvedDependency(
+                    module_name=module_path,
+                    class_name=param.annotation.__name__,
+                    type=param.annotation,
+                    full_class_path=f"{module_path}.{param.annotation.__name__}"
+                )
+
+        return MethodDependency(
+            resolved=resolved_dependencies,
+            unresolved=unresolved_dependencies
+        )

orionis/luminate/support/introspection/helpers/functions.py

@@ -0,0 +1,281 @@
+from typing import Any, Type
+import inspect
+import importlib
+
+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:
+            # Try to create an instance to verify it's truly concrete
+            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/luminate/support/{inspection/reflexion_abstract.py → introspection/reflect_abstract.py}

@@ -3,7 +3,7 @@ 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
+from orionis.luminate.support.introspection.contracts.reflexion_abstract import IReflexionAbstract
 
 ABC = TypeVar('ABC', bound=abc.ABC)