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

orionis/container/contracts/container.py

@@ -1,7 +1,8 @@
 from abc import ABC, abstractmethod
-from typing import Any, Callable
+from typing import Any, Callable, Optional
 from orionis.container.enums.lifetimes import Lifetime
 from orionis.container.entities.binding import Binding
+from orionis.services.introspection.dependencies.entities.resolve_argument import ResolveArguments
 
 class IContainer(ABC):
     """
@@ -17,7 +18,7 @@ class IContainer(ABC):
         *,
         alias: str = None,
         enforce_decoupling: bool = False
-    ) -> bool:
+    ) -> Optional[bool]:
         """
         Registers a service with a singleton lifetime.
 
@@ -47,7 +48,7 @@ class IContainer(ABC):
         *,
         alias: str = None,
         enforce_decoupling: bool = False
-    ) -> bool:
+    ) -> Optional[bool]:
         """
         Registers a service with a transient lifetime.
 
@@ -77,7 +78,7 @@ class IContainer(ABC):
         *,
         alias: str = None,
         enforce_decoupling: bool = False
-    ) -> bool:
+    ) -> Optional[bool]:
         """
         Registers a service with a scoped lifetime.
 
@@ -107,7 +108,7 @@ class IContainer(ABC):
         *,
         alias: str = None,
         enforce_decoupling: bool = False
-    ) -> bool:
+    ) -> Optional[bool]:
         """
         Registers an instance of a class or interface in the container.
 
@@ -137,7 +138,7 @@ class IContainer(ABC):
         fn: Callable[..., Any],
         *,
         lifetime: Lifetime = Lifetime.TRANSIENT
-    ) -> bool:
+    ) -> Optional[bool]:
         """
         Registers a function or factory under a given alias.
 
@@ -157,32 +158,6 @@ class IContainer(ABC):
         """
         pass
 
-    @abstractmethod
-    def make(
-        self,
-        abstract_or_alias: Any,
-        *args: tuple,
-        **kwargs: dict
-    ) -> Any:
-        """
-        Resolves and returns an instance of the requested service.
-
-        Parameters
-        ----------
-        abstract_or_alias : Any
-            The abstract class, interface, or alias (str) to resolve.
-        *args : tuple
-            Positional arguments to pass to the constructor of the resolved service.
-        **kwargs : dict
-            Keyword arguments to pass to the constructor of the resolved service.
-
-        Returns
-        -------
-        Any
-            An instance of the requested service.
-        """
-        pass
-
     @abstractmethod
     def bound(
         self,
@@ -207,7 +182,7 @@ class IContainer(ABC):
     def getBinding(
         self,
         abstract_or_alias: Any
-    ) -> Binding:
+    ) -> Optional[Binding]:
         """
         Retrieves the binding for the requested abstract type or alias.
 
@@ -268,4 +243,180 @@ class IContainer(ABC):
             ...
         # Scoped services are automatically disposed here
         """
+        pass
+
+    @abstractmethod
+    def resolveDependencyArguments(
+        self,
+        name: Optional[str],
+        dependencies: Optional[ResolveArguments]
+    ) -> dict:
+        """
+        Public method to resolve dependencies for a given class or callable.
+
+        This method serves as the public interface for resolving dependencies.
+        It wraps the internal dependency resolution logic and provides error
+        handling to ensure that any exceptions are communicated clearly.
+
+        Parameters
+        ----------
+        name : str or None
+            The name of the class or callable whose dependencies are being resolved.
+            Used for error reporting and context.
+        dependencies : ResolveArguments or None
+            The dependencies object containing resolved and unresolved arguments,
+            as extracted by reflection from the target's signature.
+
+        Returns
+        -------
+        dict
+            A dictionary mapping parameter names to their resolved values. Each key
+            is the name of a constructor or callable parameter, and each value is
+            the resolved dependency instance or value.
+
+        Raises
+        ------
+        OrionisContainerException
+            If any required dependency cannot be resolved, if there are unresolved
+            arguments, or if a dependency refers to a built-in type.
+        """
+        pass
+
+    @abstractmethod
+    def make(
+        self,
+        type_: Any,
+        *args: tuple,
+        **kwargs: dict
+    ) -> Any:
+        """
+        Resolve and instantiate a service or type.
+
+        This method attempts to resolve and instantiate the requested service or type.
+        It first checks if the type is registered in the container and, if so, resolves
+        it according to its binding and lifetime. If the type is not registered but is
+        a class, it attempts to auto-resolve it by constructing it and resolving its
+        dependencies recursively. If neither approach is possible, an exception is raised.
+
+        Parameters
+        ----------
+        type_ : Any
+            The abstract type, class, or alias to resolve. This can be a class, interface,
+            or a string alias registered in the container.
+        *args : tuple
+            Positional arguments to pass to the constructor or factory function.
+        **kwargs : dict
+            Keyword arguments to pass to the constructor or factory function.
+
+        Returns
+        -------
+        Any
+            The resolved and instantiated service or object. If the type is registered,
+            the instance is created according to its binding's lifetime (singleton,
+            transient, or scoped). If the type is not registered but is a class,
+            a new instance is created with its dependencies resolved automatically.
+
+        Raises
+        ------
+        OrionisContainerException
+            If the requested service or type is not registered in the container and
+            cannot be auto-resolved.
+
+        Notes
+        -----
+        - If the type is registered, the container's binding and lifetime rules are used.
+        - If the type is not registered but is a class, auto-resolution is attempted.
+        - If the type cannot be resolved by either method, an exception is raised.
+        """
+        pass
+
+    @abstractmethod
+    def resolve(
+        self,
+        binding: Binding,
+        *args,
+        **kwargs
+    ):
+        """
+        Resolves an instance from a binding according to its lifetime.
+
+        Parameters
+        ----------
+        binding : Binding
+            The binding to resolve.
+        *args : tuple
+            Additional positional arguments to pass to the constructor.
+        **kwargs : dict
+            Additional keyword arguments to pass to the constructor.
+
+        Returns
+        -------
+        Any
+            The resolved instance.
+
+        Raises
+        ------
+        OrionisContainerException
+            If the binding is not an instance of Binding or if the lifetime is not supported.
+        """
+        pass
+
+    @abstractmethod
+    def resolveWithoutContainer(
+        self,
+        type_: Callable[..., Any],
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Forces resolution of a type whether it's registered in the container or not.
+
+        Parameters
+        ----------
+        type_ : Callable[..., Any]
+            The type or callable to resolve.
+        *args : tuple
+            Positional arguments to pass to the constructor/callable.
+        **kwargs : dict
+            Keyword arguments to pass to the constructor/callable.
+
+        Returns
+        -------
+        Any
+            The resolved instance.
+
+        Raises
+        ------
+        OrionisContainerException
+            If the type cannot be resolved.
+        """
+        pass
+
+    @abstractmethod
+    def call(
+        self,
+        instance: Any,
+        method_name: str,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Call a method on an instance with automatic dependency injection.
+
+        Parameters
+        ----------
+        instance : Any
+            The instance on which to call the method.
+        method_name : str
+            The name of the method to call.
+        *args : tuple
+            Positional arguments to pass to the method.
+        **kwargs : dict
+            Keyword arguments to pass to the method.
+
+        Returns
+        -------
+        Any
+            The result of the method call.
+        """
         pass

orionis/foundation/config/database/entities/mysql.py

@@ -1,5 +1,4 @@
 from dataclasses import dataclass, field
-from typing import Optional
 from orionis.foundation.config.database.enums import (
     MySQLCharset,
     MySQLCollation,

orionis/metadata/framework.py

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

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

@@ -1,8 +1,7 @@
 from abc import ABC, abstractmethod
 import inspect
 from typing import List, 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 IReflectionAbstract(ABC):
     """
@@ -822,13 +821,13 @@ class IReflectionAbstract(ABC):
         pass
 
     @abstractmethod
-    def getConstructorDependencies(self) -> ClassDependency:
+    def getConstructorDependencies(self) -> ResolveArguments:
         """
         Get the resolved and unresolved dependencies from the constructor of the reflected 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)
@@ -836,7 +835,7 @@ class IReflectionAbstract(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 specific method of the reflected class.
 
@@ -847,7 +846,7 @@ class IReflectionAbstract(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/abstract/reflection.py

@@ -3,8 +3,7 @@ import keyword
 from abc import ABC
 from typing import List, Type
 from orionis.services.introspection.abstract.contracts.reflection import IReflectionAbstract
-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,
@@ -1382,20 +1381,20 @@ class ReflectionAbstract(IReflectionAbstract):
 
         return prop.fget.__doc__ if prop.fget else None
 
-    def getConstructorDependencies(self) -> ClassDependency:
+    def getConstructorDependencies(self) -> ResolveArguments:
         """
         Get the resolved and unresolved dependencies from the constructor.
 
         Returns
         -------
-        ClassDependency
+        ResolveArguments
             A structured representation of the constructor dependencies containing
             resolved dependencies (with names and values) and unresolved dependencies
             (parameter names without default values or annotations).
         """
         return ReflectDependencies(self.__abstract).getConstructorDependencies()
 
-    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+    def getMethodDependencies(self, method_name: str) -> ResolveArguments:
         """
         Get the resolved and unresolved dependencies from a specific method.
 
@@ -1406,7 +1405,7 @@ class ReflectionAbstract(IReflectionAbstract):
 
         Returns
         -------
-        MethodDependency
+        ResolveArguments
             A structured representation of the method dependencies containing
             resolved dependencies (with names and values) and unresolved dependencies
             (parameter names without default values or annotations).

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

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from orionis.services.introspection.dependencies.entities.resolve_argument import ResolveArguments
 
 class IReflectionCallable(ABC):
     """
@@ -156,7 +157,7 @@ class IReflectionCallable(ABC):
         pass
 
     @abstractmethod
-    def getDependencies(self):
+    def getDependencies(self) -> ResolveArguments:
         """
         Analyze the callable and retrieve its dependency information.
 
@@ -166,7 +167,7 @@ class IReflectionCallable(ABC):
 
         Returns
         -------
-        CallableDependency
+        ResolveArguments
             An object containing information about the callable's dependencies:
             - resolved : dict
                 A dictionary mapping parameter names to their resolved values

orionis/services/introspection/callables/reflection.py

@@ -1,7 +1,7 @@
 import inspect
 from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.introspection.callables.contracts.reflection import IReflectionCallable
-from orionis.services.introspection.dependencies.entities.callable_dependencies import CallableDependency
+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,
@@ -210,7 +210,7 @@ class ReflectionCallable(IReflectionCallable):
         """
         return inspect.signature(self.__function)
 
-    def getDependencies(self) -> CallableDependency:
+    def getDependencies(self) -> ResolveArguments:
         """
         Analyze the callable and retrieve its dependency information.
 
@@ -220,7 +220,7 @@ class ReflectionCallable(IReflectionCallable):
 
         Returns
         -------
-        CallableDependency
+        ResolveArguments
             An object containing information about the callable's dependencies:
             - resolved : dict
                 A dictionary mapping parameter names to their resolved values
@@ -235,4 +235,4 @@ class ReflectionCallable(IReflectionCallable):
         the callable and determine which dependencies are satisfied and
         which remain unresolved for dependency injection purposes.
         """
-        return ReflectDependencies().getCallableDependencies(self.__function)
+        return ReflectDependencies(self.__function).getCallableDependencies()

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

@@ -1,8 +1,7 @@
 from abc import ABC, abstractmethod
 import inspect
 from typing import Any, Callable, List, 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
 from orionis.services.introspection.instances.reflection import ReflectionInstance
 
 class IReflectionConcrete(ABC):
@@ -952,13 +951,13 @@ class IReflectionConcrete(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).
@@ -966,7 +965,7 @@ class IReflectionConcrete(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.
 
@@ -977,7 +976,7 @@ class IReflectionConcrete(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/concretes/reflection.py

@@ -4,8 +4,7 @@ import keyword
 from typing import Any, Callable, List, Type
 from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.introspection.concretes.contracts.reflection import IReflectionConcrete
-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,
@@ -1538,7 +1537,7 @@ class ReflectionConcrete(IReflectionConcrete):
         """
         return inspect.signature(self._concrete.__init__)
 
-    def getConstructorDependencies(self) -> ClassDependency:
+    def getConstructorDependencies(self) -> ResolveArguments:
         """
         Get dependency analysis for the class constructor.
 
@@ -1547,14 +1546,14 @@ class ReflectionConcrete(IReflectionConcrete):
 
         Returns
         -------
-        ClassDependency
+        ResolveArguments
             A structured representation containing resolved dependencies
             (with default values/annotations) and unresolved dependencies
             (parameters without defaults or type information).
         """
         return ReflectDependencies(self._concrete).getConstructorDependencies()
 
-    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+    def getMethodDependencies(self, method_name: str) -> ResolveArguments:
         """
         Get dependency analysis for a specific method.
 
@@ -1568,7 +1567,7 @@ class ReflectionConcrete(IReflectionConcrete):
 
         Returns
         -------
-        MethodDependency
+        ResolveArguments
             A structured representation containing resolved dependencies
             (with default values/annotations) and unresolved dependencies
             (parameters without defaults or type information).

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

@@ -1,6 +1,5 @@
 from abc import ABC, abstractmethod
-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 IReflectDependencies(ABC):
     """
@@ -12,41 +11,106 @@ class IReflectDependencies(ABC):
     """
 
     @abstractmethod
-    def getConstructorDependencies(self) -> ClassDependency:
+    def getConstructorDependencies(self) -> ResolveArguments:
         """
-        Retrieve dependency information from the class constructor.
+        Inspects the constructor (__init__) method of the target class to identify and categorize
+        its parameter dependencies into resolved and unresolved categories.
+
+        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
         -------
-        ClassDependency
-            An object containing details about the constructor's dependencies.
-            The object includes:
-                - resolved : dict
-                    Mapping of dependency names to their resolved values.
-                - unresolved : list
-                    List of dependency names that are unresolved (i.e., lacking
-                    default values or type 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 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.
         """
         pass
 
-    def getMethodDependencies(self, method_name: str) -> MethodDependency:
+    @abstractmethod
+    def getMethodDependencies(self, method_name: str) -> ResolveArguments:
         """
-        Retrieve dependency information from a specified method.
+        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
         ----------
         method_name : str
-            The name of the method whose dependencies are to be inspected.
+            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
-            An object containing details about the method's dependencies.
-            The object includes:
-                - resolved : dict
-                    Mapping of dependency names to their resolved values.
-                - unresolved : list
-                    List of dependency names that are unresolved (i.e., lacking
-                    default values or type 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.
+        """
+        pass
+
+    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.
+
+        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.
+
+        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.
+
+        Raises
+        ------
+        ReflectionValueError
+            If the target object is not callable or if the callable's signature cannot be inspected.
+
+        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.
         """
         pass