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

orionis/luminate/support/introspection/reflect_decorators.py

@@ -0,0 +1,335 @@
+import ast
+import inspect
+import re
+from typing import List, Type
+from dataclasses import dataclass
+
+@dataclass
+class ClassDecorators:
+    """
+    ClassDecorators is a dataclass that encapsulates information about class decorators.
+
+    Attributes
+    ----------
+    user_defined : tuple[str, ...]
+        A tuple containing the names of user-defined decorators applied to a class.
+    native : tuple[str, ...]
+        A tuple containing the names of native or built-in decorators applied to a class.
+    all : tuple[str, ...]
+        A tuple containing the names of all decorators (both user-defined and native) applied to a class.
+    """
+    user_defined: tuple[str, ...]
+    native: tuple[str, ...]
+    all: tuple[str, ...]
+
+@dataclass
+class MethodDecorators:
+    """
+    MethodDecorators is a dataclass that encapsulates information about method decorators.
+
+    Attributes
+    ----------
+    user_defined : tuple[str, ...]
+        A tuple containing the names of user-defined decorators applied to a method.
+    native : tuple[str, ...]
+        A tuple containing the names of native or built-in decorators applied to a method.
+    all : tuple[str, ...]
+        A tuple containing the names of all decorators (both user-defined and native) applied to a method.
+    """
+    user_defined: tuple[str, ...]
+    native: tuple[str, ...]
+    all: tuple[str, ...]
+
+class ReflectDecorators(ast.NodeVisitor):
+    """
+    A class to analyze and extract decorators applied to a specific class or its methods.
+
+    This class uses the `ast` module to parse the source code of a given class and
+    extract the names of decorators applied to the class or its methods.
+
+    Parameters
+    ----------
+    cls : Type
+        The class to analyze for decorators.
+
+    Attributes
+    ----------
+    decorators : List[str]
+        A list of unique decorator names applied to the class or its methods.
+
+    Methods
+    -------
+    parse()
+        Parses the source code of the class and extracts decorator names.
+    visit_FunctionDef(node)
+        Visits function definitions in the AST and extracts their decorators.
+    visit_ClassDef(node)
+        Visits the class definition in the AST and extracts its decorators.
+    get_class_decorators() -> List[str]
+        Retrieves the decorators applied to the class itself.
+    get_method_decorators(method_name: str) -> List[str]
+        Retrieves the decorators for a specific method in the class.
+    """
+
+    def __init__(self, cls: Type):
+        """
+        Initializes the ReflectiveDecorators with the class to analyze.
+
+        Parameters
+        ----------
+        cls : Type
+            The class to analyze for decorators.
+        """
+        self._decorators: List[str] = []
+        self._method_decorators: dict = {}
+        self._class_decorators: List[str] = []
+        self._cls = cls
+        self._parsed = False
+
+    def visit_ParseSource(self) -> None:
+        """
+        Parses the source code of the class and extracts decorator names.
+
+        This method retrieves the source code of the class using `inspect.getsource`,
+        parses it into an abstract syntax tree (AST), and visits relevant nodes
+        to extract decorator names.
+
+        Returns
+        -------
+        dict
+            A dictionary containing lists of decorators:
+            - 'decorators': All unique decorators found in the class and its methods.
+            - 'method_decorators': A dictionary mapping method names to their decorators.
+            - 'class_decorators': A list of decorators applied to the class itself.
+        """
+        if not self._parsed:
+
+            # Try to get the source code of the class
+            try:
+                source = inspect.getsource(self._cls)
+            except (OSError, TypeError):
+                source = ""
+
+            # Parsed flag to avoid re-parsing
+            self._parsed = True
+
+            # If source code is not available, return empty lists
+            if not source:
+                return
+
+            # Parse the source code into an AST
+            tree = ast.parse(source)
+
+            # Visit the AST to extract decorators
+            self.visit(tree)
+
+            # Remove duplicates and non-decorator entries
+            self._decorators = list(set(self._decorators))
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """
+        Visits function definitions in the AST and extracts their decorators.
+
+        Parameters
+        ----------
+        node : ast.FunctionDef
+            The function definition node in the AST.
+
+        Returns
+        -------
+        None
+        """
+        method_decos = []
+        for deco in node.decorator_list:
+            if isinstance(deco, ast.Name):
+                self._decorators.append(deco.id)
+                method_decos.append(deco.id)
+            elif isinstance(deco, ast.Call):
+                # Handles decorators with arguments like @deco(arg)
+                if isinstance(deco.func, ast.Name):
+                    self._decorators.append(deco.func.id)
+                    method_decos.append(deco.func.id)
+            elif isinstance(deco, ast.Attribute):
+                self._decorators.append(deco.attr)
+                method_decos.append(deco.attr)
+
+        # Store method-specific decorators
+        self._method_decorators[node.name] = method_decos
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """
+        Visits the class definition in the AST and extracts its decorators.
+
+        Parameters
+        ----------
+        node : ast.ClassDef
+            The class definition node in the AST.
+
+        Returns
+        -------
+        None
+        """
+        if node.name == self._cls.__name__:
+            for deco in node.decorator_list:
+                if isinstance(deco, ast.Name):
+                    self._decorators.append(deco.id)
+                    self._class_decorators.append(deco.id)
+                elif isinstance(deco, ast.Call):
+                    # Handles decorators with arguments like @deco(arg)
+                    if isinstance(deco.func, ast.Name):
+                        self._decorators.append(deco.func.id)
+                        self._class_decorators.append(deco.func.id)
+                elif isinstance(deco, ast.Attribute):
+                    self._decorators.append(deco.attr)
+                    self._class_decorators.append(deco.attr)
+
+            # Visit methods within the class
+            for child in node.body:
+                if isinstance(child, ast.FunctionDef):
+                    self.visit_FunctionDef(child)
+
+            # No need to visit deeper
+            return
+
+    def visit_NativeDecorator(self, decorator_name: str) -> bool:
+        """
+        Checks if a decorator name matches Python's native decorator patterns.
+        Parameters
+        ----------
+        decorator_name : str
+            The name of the decorator to check.
+        Returns
+        -------
+        bool
+            True if the decorator name matches any of the predefined native patterns,
+            False otherwise.
+        Notes
+        -----
+        The method uses a list of regular expressions to identify native Python
+        decorators, including built-ins, standard library modules (e.g., `functools`,
+        `dataclasses`, `contextlib`), and other commonly used patterns. It also
+        accounts for deprecated or obsolete decorators.
+        """
+
+        native_decorator_regular_expr = [
+            # Built-ins
+            r"^property$",
+            r"^\w+\.setter$",
+            r"^\w+\.deleter$",
+            r"^classmethod$",
+            r"^staticmethod$",
+
+            # abc module
+            r"^abstractmethod$",
+            r"^abstractclassmethod$",
+            r"^abstractstaticmethod$",
+
+            # functools
+            r"^functools\.cache$",
+            r"^functools\.lru_cache(\(.*\))?$",
+            r"^functools\.cached_property$",
+            r"^functools\.singledispatch$",
+            r"^functools\.singledispatchmethod$",
+            r"^functools\.wraps(\(.*\))?$",
+
+            # dataclasses
+            r"^dataclasses\.dataclass(\(.*\))?$",
+
+            # contextlib
+            r"^contextlib\.contextmanager$",
+
+            # typing
+            r"^typing\.final$",
+            r"^typing\.overload$",
+
+            # enum
+            r"^enum\.unique$",
+
+            # asyncio (obsoleto)
+            r"^asyncio\.coroutine$",
+
+            # unittest.mock
+            r"^unittest\.mock\.patch(\(.*\))?$",
+
+            # Añadidos adicionales
+            r"^contextlib\.asynccontextmanager$",
+            r"^typing\.runtime_checkable$",
+            r"^collections\.abc\.abstractproperty$",
+        ]
+
+        return any(re.fullmatch(pattern, decorator_name) for pattern in native_decorator_regular_expr)
+
+    def getClassDecorators(self) -> ClassDecorators:
+        """
+        Retrieves the decorators applied to the class itself.
+
+        Returns
+        -------
+        ClassDecorators
+            An object containing lists of decorator names for the class.
+        """
+
+        # Parse the source code to extract decorators
+        self.visit_ParseSource()
+
+        # Filter decorators into user-defined and native
+        user_defined = []
+        native = []
+
+        # Filter decorators into user-defined and native
+        for deco in self._class_decorators:
+            if not self.visit_NativeDecorator(deco):
+                user_defined.append(deco)
+            else:
+                native.append(deco)
+
+        # Return a ClassDecorators object containing the filtered lists
+        return ClassDecorators(
+            user_defined=tuple(user_defined),
+            native=tuple(native),
+            all=tuple(self._class_decorators)
+        )
+
+    def getMethodDecorators(self, method_name: str = None) -> MethodDecorators:
+        """
+        Retrieves the decorators for a specific method in the class.
+
+        Parameters
+        ----------
+        method_name : str
+            The name of the method to retrieve decorators for.
+
+        Returns
+        -------
+        MethodDecorators
+            An object containing lists of decorator names for the specified method.
+        """
+
+        # Parse the source code to extract decorators
+        self.visit_ParseSource()
+
+        # Handle mangled names for private methods
+        # Check if the method name is mangled (private)
+        if method_name.startswith("__") and not method_name.endswith("__"):
+            method_name = f"_{self._cls.__name__}{method_name}"
+
+        # Get the decorators for the specified method
+        decorators = self._method_decorators.get(method_name, [])
+
+        # Filter decorators into user-defined and native
+        user_defined = []
+        native = []
+
+        # Filter decorators into user-defined and native
+        for deco in decorators:
+            if not self.visit_NativeDecorator(deco):
+                user_defined.append(deco)
+            else:
+                native.append(deco)
+
+        # Return a MethodDecorators object containing the filtered lists
+        return MethodDecorators(
+            user_defined=tuple(user_defined),
+            native=tuple(native),
+            all=tuple(decorators)
+        )

orionis/luminate/support/{inspection → introspection}/reflection.py

@@ -1,20 +1,14 @@
 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,
-    _ensure_user_defined_class_instance,
-    _ensure_valid_class_name,
-    _ensure_valid_module,
-)
-from orionis.luminate.support.inspection.reflexion_abstract import ReflexionAbstract
-from orionis.luminate.support.inspection.reflexion_concrete import ReflexionConcrete
-from orionis.luminate.support.inspection.reflexion_concrete_with_abstract import ReflexionConcreteWithAbstract
-from orionis.luminate.support.inspection.reflexion_instance import ReflexionInstance
-from orionis.luminate.support.inspection.reflexion_instance_with_abstract import ReflexionInstanceWithAbstract
-from orionis.luminate.support.inspection.reflexion_module import ReflexionModule
-from orionis.luminate.support.inspection.reflexion_module_with_classname import ReflexionModuleWithClassName
+from orionis.luminate.support.introspection.helpers.functions import HelpersReflection
+from orionis.luminate.support.introspection.reflect_abstract import ReflexionAbstract
+from orionis.luminate.support.introspection.reflexion_concrete import ReflexionConcrete
+from orionis.luminate.support.introspection.reflexion_concrete_with_abstract import ReflexionConcreteWithAbstract
+from orionis.luminate.support.introspection.reflection_instance import ReflectionInstance
+from orionis.luminate.support.introspection.reflexion_instance_with_abstract import ReflexionInstanceWithAbstract
+from orionis.luminate.support.introspection.reflexion_module import ReflexionModule
+from orionis.luminate.support.introspection.reflexion_module_with_classname import ReflexionModuleWithClassName
 
 T = TypeVar('T')
 ABC = TypeVar('ABC', bound=abc.ABC)
@@ -45,7 +39,7 @@ class Reflection(IReflection):
     """
 
     @staticmethod
-    def instance(instance: Any) -> 'ReflexionInstance':
+    def instance(instance: Any) -> 'ReflectionInstance':
         """Create a reflection object for a class instance.
 
         Parameters
@@ -55,7 +49,7 @@ class Reflection(IReflection):
 
         Returns
         -------
-        ReflexionInstance
+        ReflectionInstance
             A reflection object encapsulating the instance
 
         Raises
@@ -65,8 +59,8 @@ class Reflection(IReflection):
         ValueError
             If the instance is from builtins, abc, or __main__
         """
-        _ensure_user_defined_class_instance(instance)
-        return ReflexionInstance(instance)
+        HelpersReflection.ensureUserDefinedClassInstance(instance)
+        return ReflectionInstance(instance)
 
     @staticmethod
     def instanceWithAbstract(instance: Any, abstract: Type[ABC]) -> 'ReflexionInstanceWithAbstract':
@@ -91,8 +85,8 @@ class Reflection(IReflection):
         ValueError
             If the instance is invalid or abstract is not actually abstract
         """
-        _ensure_user_defined_class_instance(instance)
-        _ensure_abstract_class(abstract)
+        HelpersReflection.ensureUserDefinedClassInstance(instance)
+        HelpersReflection.ensureAbstractClass(abstract)
         return ReflexionInstanceWithAbstract(instance, abstract)
 
     @staticmethod
@@ -116,7 +110,7 @@ class Reflection(IReflection):
         ValueError
             If the class is not abstract
         """
-        _ensure_abstract_class(abstract)
+        HelpersReflection.ensureAbstractClass(abstract)
         return ReflexionAbstract(abstract)
 
     @staticmethod
@@ -140,7 +134,7 @@ class Reflection(IReflection):
         ValueError
             If the class is abstract or cannot be instantiated
         """
-        _ensure_instantiable_class(concrete)
+        HelpersReflection.ensureInstantiableClass(concrete)
         return ReflexionConcrete(concrete)
 
     @staticmethod
@@ -166,8 +160,8 @@ class Reflection(IReflection):
         ValueError
             If concrete is not instantiable or abstract is not actually abstract
         """
-        _ensure_instantiable_class(concrete)
-        _ensure_abstract_class(abstract)
+        HelpersReflection.ensureInstantiableClass(concrete)
+        HelpersReflection.ensureAbstractClass(abstract)
         return ReflexionConcreteWithAbstract(concrete, abstract)
 
     @staticmethod
@@ -191,7 +185,7 @@ class Reflection(IReflection):
         ValueError
             If the module cannot be imported
         """
-        _ensure_valid_module(module)
+        HelpersReflection.ensureValidModule(module)
         return ReflexionModule(module)
 
     @staticmethod
@@ -217,6 +211,6 @@ class Reflection(IReflection):
         ValueError
             If the module cannot be imported or the class doesn't exist in it
         """
-        _ensure_valid_module(module)
-        _ensure_valid_class_name(module, class_name)
+        HelpersReflection.ensureValidModule(module)
+        HelpersReflection.ensureValidClassName(class_name)
         return ReflexionModuleWithClassName(module, class_name)