orionis 0.449.0__py3-none-any.whl → 0.451.0__py3-none-any.whl

orionis/services/introspection/dependencies/entities/argument.py

@@ -0,0 +1,95 @@
+from dataclasses import dataclass
+from typing import Optional, Type, Any
+from orionis.services.introspection.exceptions import ReflectionTypeError
+
+@dataclass(frozen=True, kw_only=True)
+class Argument:
+    """
+    Represents a function or method argument with type information and resolution status.
+
+    This class encapsulates metadata about an argument including its type information,
+    module location, resolution status, and optional default value. It is primarily
+    used in dependency injection and introspection systems to track argument details
+    and validate type consistency.
+
+    Attributes
+    ----------
+    resolved : bool
+        Flag indicating whether the argument has been resolved or processed.
+    module_name : str
+        The name of the module where the argument's type is defined.
+    class_name : str
+        The name of the class representing the argument's type.
+    type : Type[Any]
+        The Python type object representing the argument's type.
+    full_class_path : str
+        The complete dotted path to the argument's type (module.class).
+    default : Optional[Any], default=None
+        The default value for the argument, if any. When None, indicates
+        the argument is required and must be explicitly provided.
+
+    Notes
+    -----
+    The class performs automatic validation during initialization through the
+    __post_init__ method. Validation ensures type consistency and completeness
+    of required fields when no default value is provided.
+    """
+    resolved: bool
+    module_name: str
+    class_name: str
+    type: Type[Any]
+    full_class_path: str
+    default: Optional[Any] = None
+
+    def __post_init__(self):
+        """
+        Validate all fields during initialization to ensure data integrity.
+
+        This method performs comprehensive validation of the Argument instance fields
+        after dataclass initialization. Validation ensures that all required string
+        fields are properly typed and that the type field is not None when no default
+        value is provided.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs in-place validation
+            and raises exceptions if validation fails.
+
+        Raises
+        ------
+        ReflectionTypeError
+            If module_name, class_name, or full_class_path are not string types.
+        ValueError
+            If the 'type' field is None when default is None, indicating missing
+            type information for a required argument.
+
+        Notes
+        -----
+        Validation is conditionally performed only when default is None. Arguments
+        with default values are assumed to have sufficient type information and
+        skip the validation process.
+        """
+        # Skip validation when default value is provided
+        # Arguments with defaults have implicit type information
+        if self.default is None and self.resolved:
+
+            # Validate module_name is a string type
+            # Module names must be valid string identifiers
+            if not isinstance(self.module_name, str):
+                raise ReflectionTypeError(f"module_name must be str, got {type(self.module_name).__name__}")
+
+            # Validate class_name is a string type
+            # Class names must be valid string identifiers
+            if not isinstance(self.class_name, str):
+                raise ReflectionTypeError(f"class_name must be str, got {type(self.class_name).__name__}")
+
+            # Validate type field is not None for required arguments
+            # Type information is essential for dependency resolution
+            if self.type is None:
+                raise ValueError("The 'type' field must not be None. Please provide a valid Python type object for the dependency.")
+
+            # Validate full_class_path is a string type
+            # Full class path must be a valid dotted string notation
+            if not isinstance(self.full_class_path, str):
+                raise ReflectionTypeError(f"full_class_path must be str, got {type(self.full_class_path).__name__}")

orionis/services/introspection/dependencies/entities/resolve_argument.py

@@ -0,0 +1,82 @@
+from dataclasses import dataclass
+from typing import Dict
+from orionis.services.introspection.dependencies.entities.argument import Argument
+from orionis.services.introspection.exceptions import ReflectionTypeError
+from orionis.support.entities.base import BaseEntity
+
+@dataclass(frozen=True, kw_only=True)
+class ResolveArguments(BaseEntity):
+    """
+    Represents the dependencies of a class, distinguishing between resolved and unresolved dependencies.
+
+    This class encapsulates both successfully resolved dependencies (with their corresponding
+    Argument instances) and unresolved dependencies that could not be satisfied during
+    dependency injection or reflection analysis.
+
+    Parameters
+    ----------
+    resolved : Dict[str, Argument]
+        Dictionary mapping dependency names to their corresponding Argument instances
+        that have been successfully resolved.
+    unresolved : Dict[str, Argument]
+        Dictionary mapping dependency names to their corresponding Argument instances
+        that could not be resolved during dependency analysis.
+
+    Attributes
+    ----------
+    resolved : Dict[str, Argument]
+        The resolved dependencies for the class, where each key is a dependency name
+        and each value is an Argument instance containing the resolved information.
+    unresolved : Dict[str, Argument]
+        The unresolved dependency names mapped to their Argument instances, representing
+        dependencies that could not be satisfied.
+
+    Raises
+    ------
+    ReflectionTypeError
+        If 'resolved' is not a dictionary or 'unresolved' is not a dictionary.
+    """
+
+    # Resolved dependencies as a dictionary of names to Argument instances
+    resolved: Dict[str, Argument]
+
+    # Unresolved dependencies as a dictionary of names to Argument instances
+    unresolved: Dict[str, Argument]
+
+    def __post_init__(self):
+        """
+        Validates the types and contents of the resolved and unresolved attributes.
+
+        This method is automatically called by the dataclass after object initialization
+        to ensure that both attributes are dictionaries with the correct types. It performs
+        runtime type checking to maintain data integrity and provide clear error messages
+        when invalid types are provided.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method performs validation only and does not return any value.
+
+        Raises
+        ------
+        ReflectionTypeError
+            If 'resolved' is not a dict or 'unresolved' is not a dict.
+        """
+
+        # Validate that the 'resolved' attribute is a dictionary type
+        # This ensures that resolved dependencies can be properly accessed by name
+        if not isinstance(self.resolved, dict):
+            raise ReflectionTypeError(
+                f"'resolved' must be a dict, got {type(self.resolved).__name__}"
+            )
+
+        # Validate that the 'unresolved' attribute is a dictionary type
+        # This ensures that unresolved dependencies maintain the same structure as resolved ones
+        if not isinstance(self.unresolved, dict):
+            raise ReflectionTypeError(
+                f"'unresolved' must be a dict, got {type(self.unresolved).__name__}"
+            )

orionis/services/introspection/dependencies/reflection.py

@@ -1,10 +1,8 @@
 import inspect
-from typing import Any, Dict, List
+from typing import Any, Dict
 from orionis.services.introspection.dependencies.contracts.reflection import IReflectDependencies
-from orionis.services.introspection.dependencies.entities.callable_dependencies import CallableDependency
-from orionis.services.introspection.dependencies.entities.class_dependencies import ClassDependency
-from orionis.services.introspection.dependencies.entities.method_dependencies import MethodDependency
-from orionis.services.introspection.dependencies.entities.known_dependencies import KnownDependency
+from orionis.services.introspection.dependencies.entities.argument import Argument
+from orionis.services.introspection.dependencies.entities.resolve_argument import ResolveArguments
 from orionis.services.introspection.exceptions import ReflectionValueError
 
 class ReflectDependencies(IReflectDependencies):
@@ -77,150 +75,222 @@ class ReflectDependencies(IReflectDependencies):
         except (ReflectionValueError, TypeError, Exception) as e:
             raise ReflectionValueError(f"Unable to inspect signature of {target}: {str(e)}")
 
-    def getConstructorDependencies(self) -> ClassDependency:
+    def __getDependencies(self, signature: inspect.Signature) -> ResolveArguments:
         """
-        Get the resolved and unresolved dependencies from the constructor of the instance's class.
+        Analyze function signature parameters to categorize dependencies as resolved or unresolved.
+
+        This method examines each parameter in a function signature and determines whether
+        it can be automatically resolved for dependency injection based on type annotations
+        and default values. Parameters are categorized into two groups: those that can be
+        automatically resolved by the dependency injection system and those that require
+        manual intervention.
+
+        Parameters
+        ----------
+        signature : inspect.Signature
+            The function signature to analyze for dependencies. Must be a valid signature
+            object obtained from inspect.signature().
 
         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).
+        ResolveArguments
+            A data structure containing two dictionaries:
+
+            - resolved : Dict[str, Argument]
+                Parameters that can be automatically resolved. Includes parameters with:
+                - Type annotations from non-builtin modules
+                - Default values (regardless of type annotation)
+
+            - unresolved : Dict[str, Argument]
+                Parameters that cannot be automatically resolved. Includes parameters with:
+                - No type annotation and no default value
+                - Builtin type annotations without default values (int, str, bool, etc.)
+
+        Notes
+        -----
+        - Parameters named 'self', 'cls', 'args', 'kwargs' and variadic parameters
+          (*args, **kwargs) are automatically excluded from analysis
+        - Parameters with default values are always considered resolved, regardless
+          of their type annotation
+        - Builtin types (int, str, bool, etc.) without default values are considered
+          unresolved as they typically require explicit values
+        - Custom classes and imported types with annotations are considered resolved
+          as they can be instantiated by the dependency injection system
         """
-        signature = self.__inspectSignature(self.__target.__init__)
-        resolved_dependencies: Dict[str, Any] = {}
-        unresolved_dependencies: List[str] = []
 
+        # Initialize dictionaries to store categorized dependencies
+        resolved_dependencies: Dict[str, Argument] = {}
+        unresolved_dependencies: Dict[str, Argument] = {}
+
+        # Iterate through all parameters in the signature
         for param_name, param in signature.parameters.items():
 
             # Skip parameters that are not relevant for dependency resolution
+            # (self, cls, *args, **kwargs, etc.)
             if self.__paramSkip(param_name, param):
                 continue
 
-            # Add to the list of unresolved dependencies if it has no default value or annotation
+            # Case 1: Parameters with no annotation and no default value
+            # These cannot be resolved automatically and require manual provision
             if param.annotation is param.empty and param.default is param.empty:
-                unresolved_dependencies.append(param_name)
+                unresolved_dependencies[param_name] = Argument(
+                    resolved=False,
+                    module_name=None,
+                    class_name=None,
+                    type=Any,
+                    full_class_path=None,
+                )
                 continue
 
-            # Parameters with default values
+            # Case 2: Parameters with default values
+            # These are always considered resolved since they have fallback values
             if param.default is not param.empty:
-                resolved_dependencies[param_name] = param.default
+                resolved_dependencies[param_name] = Argument(
+                    resolved=True,
+                    module_name=type(param.default).__module__,
+                    class_name=type(param.default).__name__,
+                    type=type(param.default),
+                    full_class_path=f"{type(param.default).__module__}.{type(param.default).__name__}",
+                    default=param.default
+                )
                 continue
 
-            # If the parameter has an annotation, it is added to the list of resolved dependencies
+            # Case 3: Parameters with type annotations
             if param.annotation is not param.empty:
-                module_path = param.annotation.__module__
-                resolved_dependencies[param_name] = KnownDependency(
-                    module_name=module_path,
-                    class_name=param.annotation.__name__,
-                    type=param.annotation,
-                    full_class_path=f"{module_path}.{param.annotation.__name__}"
-                )
+                # Special handling for builtin types without defaults
+                # Builtin types (int, str, bool, etc.) are considered unresolved
+                # when they lack default values, as they typically need explicit values
+                if param.annotation.__module__ == 'builtins' and param.default is param.empty:
+                    unresolved_dependencies[param_name] = Argument(
+                        resolved=False,
+                        module_name=param.annotation.__module__,
+                        class_name=param.annotation.__name__,
+                        type=param.annotation,
+                        full_class_path=f"{param.annotation.__module__}.{param.annotation.__name__}"
+                    )
+                else:
+                    # Non-builtin types with annotations are considered resolved
+                    # as they can be instantiated by the dependency injection system
+                    resolved_dependencies[param_name] = Argument(
+                        resolved=True,
+                        module_name=param.annotation.__module__,
+                        class_name=param.annotation.__name__,
+                        type=param.annotation,
+                        full_class_path=f"{param.annotation.__module__}.{param.annotation.__name__}"
+                    )
+                continue
 
-        return ClassDependency(
+        # Return the categorized dependencies
+        return ResolveArguments(
             resolved=resolved_dependencies,
             unresolved=unresolved_dependencies
         )
 
-    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+    def getConstructorDependencies(self) -> ResolveArguments:
         """
-        Get the resolved and unresolved dependencies from a method of the instance's class.
+        Inspects the constructor (__init__) method of the target class to identify and categorize
+        its parameter dependencies into resolved and unresolved categories.
 
-        Parameters
-        ----------
-        method_name : str
-            The name of the method to inspect
+        This method analyzes the constructor's signature to determine which parameters can be
+        automatically resolved (those with type annotations or default values) and which require
+        explicit provision during instantiation.
 
         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.__target, method_name))
-        resolved_dependencies: Dict[str, Any] = {}
-        unresolved_dependencies: List[str] = []
-
-        for param_name, param in signature.parameters.items():
+        ResolveArguments
+            An object containing two dictionaries:
+            - resolved: Dict[str, Argument] mapping parameter names to Argument objects for
+              parameters that have type annotations or default values and can be automatically resolved.
+            - unresolved: Dict[str, Argument] mapping parameter names to Argument objects for
+              parameters that lack both type annotations and default values, requiring manual resolution.
 
-            # 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] = KnownDependency(
-                    module_name=module_path,
-                    class_name=param.annotation.__name__,
-                    type=param.annotation,
-                    full_class_path=f"{module_path}.{param.annotation.__name__}"
-                )
+        Raises
+        ------
+        ReflectionValueError
+            If the target object's constructor signature cannot be inspected or if the target
+            is not callable.
+
+        Notes
+        -----
+        Parameters named 'self', 'cls', 'args', 'kwargs', and variadic parameters (*args, **kwargs)
+        are automatically excluded from dependency analysis as they are not relevant for
+        dependency injection purposes.
+        """
 
-        return MethodDependency(
-            resolved=resolved_dependencies,
-            unresolved=unresolved_dependencies
-        )
+        # Extract the constructor signature from the target class
+        return self.__getDependencies(self.__inspectSignature(self.__target.__init__))
 
-    def getCallableDependencies(self, fn: callable) -> CallableDependency:
+    def getMethodDependencies(self, method_name: str) -> ResolveArguments:
         """
-        Get the resolved and unresolved dependencies from a callable function.
+        Inspects a specific method of the target class to identify and categorize
+        its parameter dependencies into resolved and unresolved categories.
+
+        This method analyzes the specified method's signature to determine which parameters
+        can be automatically resolved (those with type annotations or default values) and
+        which require explicit provision during method invocation.
 
         Parameters
         ----------
-        fn : callable
-            The function to inspect.
+        method_name : str
+            The name of the method within the target class to inspect for dependencies.
+            The method must exist as an attribute of the target object.
 
         Returns
         -------
-        MethodDependency
-            A structured representation of the callable dependencies, containing:
-            - resolved: Dictionary of resolved dependencies with their names and values.
-            - unresolved: List of unresolved dependencies (parameter names without default values or annotations).
+        ResolveArguments
+            An object containing two dictionaries:
+            - resolved: Dict[str, Argument] mapping parameter names to Argument objects for
+              parameters that have type annotations or default values and can be automatically resolved.
+            - unresolved: Dict[str, Argument] mapping parameter names to Argument objects for
+              parameters that lack both type annotations and default values, requiring manual resolution.
+
+        Raises
+        ------
+        ReflectionValueError
+            If the specified method does not exist on the target object, if the method's
+            signature cannot be inspected, or if the target is not callable.
+        AttributeError
+            If the method_name does not correspond to an existing attribute on the target object.
+
+        Notes
+        -----
+        Parameters named 'self', 'cls', 'args', 'kwargs', and variadic parameters (*args, **kwargs)
+        are automatically excluded from dependency analysis as they are not relevant for
+        dependency injection purposes.
         """
-        signature = inspect.signature(fn)
-        resolved_dependencies: Dict[str, Any] = {}
-        unresolved_dependencies: List[str] = []
 
-        for param_name, param in signature.parameters.items():
+        # Extract the method signature from the target class
+        return self.__getDependencies(self.__inspectSignature(getattr(self.__target, method_name)))
 
-            # Skip parameters that are not relevant for dependency resolution
-            if self.__paramSkip(param_name, param):
-                continue
+    def getCallableDependencies(self) -> ResolveArguments:
+        """
+        Inspects a callable target (function, lambda, or other callable object) to identify
+        and categorize its parameter dependencies into resolved and unresolved categories.
 
-            # 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
+        This method analyzes the callable's signature to determine which parameters can be
+        automatically resolved (those with type annotations or default values) and which
+        require explicit provision during function invocation.
 
-            # Parameters with default values
-            if param.default is not param.empty:
-                resolved_dependencies[param_name] = param.default
-                continue
+        Returns
+        -------
+        ResolveArguments
+            An object containing two dictionaries:
+            - resolved: Dict[str, Argument] mapping parameter names to Argument objects for
+              parameters that have type annotations or default values and can be automatically resolved.
+            - unresolved: Dict[str, Argument] mapping parameter names to Argument objects for
+              parameters that lack both type annotations and default values, requiring manual resolution.
 
-            # 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] = KnownDependency(
-                    module_name=module_path,
-                    class_name=param.annotation.__name__,
-                    type=param.annotation,
-                    full_class_path=f"{module_path}.{param.annotation.__name__}"
-                )
+        Raises
+        ------
+        ReflectionValueError
+            If the target object is not callable or if the callable's signature cannot be inspected.
 
-        return CallableDependency(
-            resolved=resolved_dependencies,
-            unresolved=unresolved_dependencies
-        )
+        Notes
+        -----
+        Parameters named 'self', 'cls', 'args', 'kwargs', and variadic parameters (*args, **kwargs)
+        are automatically excluded from dependency analysis as they are not relevant for
+        dependency injection purposes.
+        """
+
+        # Extract the callable signature from the target object
+        return self.__getDependencies(inspect.signature(self.__target))

orionis/services/introspection/instances/contracts/reflection.py

@@ -1,8 +1,7 @@
 from abc import ABC, abstractmethod
 import inspect
 from typing import Any, Callable, Dict, List, Optional, Tuple, Type
-from orionis.services.introspection.dependencies.entities.class_dependencies import ClassDependency
-from orionis.services.introspection.dependencies.entities.method_dependencies import MethodDependency
+from orionis.services.introspection.dependencies.entities.resolve_argument import ResolveArguments
 
 class IReflectionInstance(ABC):
 
@@ -836,13 +835,13 @@ class IReflectionInstance(ABC):
         pass
 
     @abstractmethod
-    def getConstructorDependencies(self) -> ClassDependency:
+    def getConstructorDependencies(self) -> ResolveArguments:
         """
         Get the resolved and unresolved dependencies from the constructor of the instance's class.
 
         Returns
         -------
-        ClassDependency
+        ResolveArguments
             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).
@@ -850,7 +849,7 @@ class IReflectionInstance(ABC):
         pass
 
     @abstractmethod
-    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+    def getMethodDependencies(self, method_name: str) -> ResolveArguments:
         """
         Get the resolved and unresolved dependencies from a method of the instance's class.
 
@@ -861,7 +860,7 @@ class IReflectionInstance(ABC):
 
         Returns
         -------
-        MethodDependency
+        ResolveArguments
             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).

orionis/services/introspection/instances/reflection.py

@@ -2,8 +2,7 @@ import inspect
 import keyword
 from typing import Any, Callable, Dict, List, Optional, Tuple, Type
 from orionis.services.asynchrony.coroutines import Coroutine
-from orionis.services.introspection.dependencies.entities.class_dependencies import ClassDependency
-from orionis.services.introspection.dependencies.entities.method_dependencies import MethodDependency
+from orionis.services.introspection.dependencies.entities.resolve_argument import ResolveArguments
 from orionis.services.introspection.dependencies.reflection import ReflectDependencies
 from orionis.services.introspection.exceptions import (
     ReflectionAttributeError,
@@ -1561,13 +1560,13 @@ class ReflectionInstance(IReflectionInstance):
         # If the property does not exist, raise an error
         raise ReflectionAttributeError(f"Property '{original_name}' does not exist on '{self.getClassName()}'.")
 
-    def getConstructorDependencies(self) -> ClassDependency:
+    def getConstructorDependencies(self) -> ResolveArguments:
         """
         Retrieves the resolved and unresolved dependencies from the constructor (__init__) of the instance's class.
 
         Returns
         -------
-        ClassDependency
+        ResolveArguments
             An object representing the constructor dependencies, including:
             - resolved : dict
                 Dictionary of resolved dependencies with their names and values.
@@ -1581,7 +1580,7 @@ class ReflectionInstance(IReflectionInstance):
         """
         return ReflectDependencies(self._instance.__class__).getConstructorDependencies()
 
-    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+    def getMethodDependencies(self, method_name: str) -> ResolveArguments:
         """
         Get the resolved and unresolved dependencies from a method of the instance's class.
 
@@ -1592,7 +1591,7 @@ class ReflectionInstance(IReflectionInstance):
 
         Returns
         -------
-        MethodDependency
+        ResolveArguments
             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).