orionis 0.320.0__py3-none-any.whl → 0.321.0__py3-none-any.whl

orionis/container/container.py

@@ -4,7 +4,7 @@ from orionis.container.contracts.container import IContainer
 from orionis.container.entities.binding import Binding
 from orionis.container.enums.lifetimes import Lifetime
 from orionis.container.exceptions.container_exception import OrionisContainerException
-from orionis.container.exceptions.type_error_exception import OrionisContainerTypeError
+from orionis.container.resolver import Resolver
 from orionis.container.validators.implements import ImplementsAbstractMethods
 from orionis.container.validators.is_abstract_class import IsAbstractClass
 from orionis.container.validators.is_callable import IsCallable
@@ -13,12 +13,9 @@ from orionis.container.validators.is_instance import IsInstance
 from orionis.container.validators.is_not_subclass import IsNotSubclass
 from orionis.container.validators.is_subclass import IsSubclass
 from orionis.container.validators.is_valid_alias import IsValidAlias
+from orionis.container.validators.lifetime import LifetimeValidator
 from orionis.services.introspection.abstract.reflection_abstract import ReflectionAbstract
 from orionis.services.introspection.callables.reflection_callable import ReflectionCallable
-from orionis.services.introspection.concretes.reflection_concrete import ReflectionConcrete
-from orionis.services.introspection.dependencies.entities.resolved_dependencies import ResolvedDependency
-from orionis.services.introspection.instances.reflection_instance import ReflectionInstance
-from orionis.services.introspection.reflection import Reflection
 
 class Container(IContainer):
 
@@ -37,9 +34,7 @@ class Container(IContainer):
     _initialized = False
 
     def __new__(
-        cls,
-        *args,
-        **kwargs
+        cls
     ) -> 'Container':
         """
         Creates and returns a singleton instance of the class.
@@ -48,12 +43,7 @@ class Container(IContainer):
         of the class exists. If an instance does not exist, it acquires a lock to
         ensure thread safety and creates the instance. Subsequent calls return the
         existing instance.
-        Parameters
-        ----------
-        *args : tuple
-            Variable length argument list.
-        **kwargs : dict
-            Arbitrary keyword arguments.
+
         Returns
         -------
         Container
@@ -471,21 +461,9 @@ class Container(IContainer):
         OrionisContainerException
             If the lifetime is not allowed for the function signature.
         """
+
         # Normalize and validate the lifetime parameter
-        if not isinstance(lifetime, Lifetime):
-            if isinstance(lifetime, str):
-                lifetime_key = lifetime.strip().upper()
-                if lifetime_key in Lifetime.__members__:
-                    lifetime = Lifetime[lifetime_key]
-                else:
-                    valid = ', '.join(Lifetime.__members__.keys())
-                    raise OrionisContainerTypeError(
-                        f"Invalid lifetime '{lifetime}'. Valid options are: {valid}."
-                    )
-            else:
-                raise OrionisContainerTypeError(
-                    f"Lifetime must be of type str or Lifetime enum, got {type(lifetime).__name__}."
-                )
+        lifetime = LifetimeValidator(lifetime)
 
         # Ensure that the alias is a valid string
         IsValidAlias(alias)
@@ -544,7 +522,7 @@ class Container(IContainer):
             or abstract_or_alias in self.__aliasses
         )
 
-    def __getService(
+    def getBinding(
         self,
         abstract_or_alias: Any
     ) -> Binding:
@@ -563,29 +541,6 @@ class Container(IContainer):
         """
         return self.__bindings.get(abstract_or_alias) or self.__aliasses.get(abstract_or_alias)
 
-    def __getFirstService(
-        self,
-        abstract_or_aliasses: list
-    ) -> Binding:
-        """
-        Retrieves the first binding from a list of abstract types or aliases.
-
-        Parameters
-        ----------
-        abstract_or_aliasses : list
-            A list of abstract classes, interfaces, or aliases (str) to retrieve.
-
-        Returns
-        -------
-        Binding
-            The first binding found in the container for the provided abstract types or aliases.
-        """
-        for item in abstract_or_aliasses:
-            binding = self.__getService(item)
-            if binding:
-                return binding
-        return None
-
     def drop(
         self,
         abstract: Callable[..., Any] = None,
@@ -665,341 +620,17 @@ class Container(IContainer):
         OrionisContainerException
             If the requested service is not registered in the container.
         """
-        # Retrieve the binding for the requested abstract or alias
-        binding = self.__getService(abstract_or_alias)
-
-        # Check if the requested service is registered in the container
-        if not binding:
+        if not self.bound(abstract_or_alias):
             raise OrionisContainerException(
                 f"The requested service '{abstract_or_alias}' is not registered in the container."
             )
 
-        # Handle based on binding type and lifetime
-        if binding.lifetime == Lifetime.TRANSIENT:
-            return self.__resolveTransient(binding, *args, **kwargs)
-        elif binding.lifetime == Lifetime.SINGLETON:
-            return self.__resolveSingleton(binding, *args, **kwargs)
-        elif binding.lifetime == Lifetime.SCOPED:
-            # TODO: Implement scoped lifetime resolution
-            raise OrionisContainerException(
-                "Scoped lifetime resolution is not yet implemented."
-            )
-
-    def __resolveTransient(self, binding: Binding, *args, **kwargs) -> Any:
-        """
-        Resolves a service with transient lifetime.
-
-        Parameters
-        ----------
-        binding : Binding
-            The binding to resolve.
-        *args : tuple
-            Positional arguments to pass to the constructor.
-        **kwargs : dict
-            Keyword arguments to pass to the constructor.
-
-        Returns
-        -------
-        Any
-            A new instance of the requested service.
-        """
-
-        # Check if the binding has a concrete class or function defined
-        if binding.concrete:
-            if args or kwargs:
-                return self.__instantiateConcreteWithArgs(binding.concrete, *args, **kwargs)
-            else:
-                return self.__instantiateConcreteReflective(binding.concrete)
-
-        # If the binding has a function defined
-        elif binding.function:
-            if args or kwargs:
-                return self.__instantiateCallableWithArgs(binding.function, *args, **kwargs)
-            else:
-                return self.__instantiateCallableReflective(binding.function)
-
-        # If neither concrete class nor function is defined
-        else:
-            raise OrionisContainerException(
-                "Cannot resolve transient binding: neither a concrete class nor a function is defined."
-            )
-
-    def __resolveSingleton(self, binding: Binding, *args, **kwargs) -> Any:
-        """
-        Resolves a service with singleton lifetime.
-
-        Parameters
-        ----------
-        binding : Binding
-            The binding to resolve.
-        *args : tuple
-            Positional arguments to pass to the constructor (only used if instance doesn't exist yet).
-        **kwargs : dict
-            Keyword arguments to pass to the constructor (only used if instance doesn't exist yet).
-
-        Returns
-        -------
-        Any
-            The singleton instance of the requested service.
-        """
-        # Return existing instance if available
-        if binding.instance:
-            return binding.instance
-
-        # Create instance if needed
-        if binding.concrete:
-            if args or kwargs:
-                binding.instance = self.__instantiateConcreteWithArgs(binding.concrete, *args, **kwargs)
-            else:
-                binding.instance = self.__instantiateConcreteReflective(binding.concrete)
-            return binding.instance
-
-        # If the binding has a function defined
-        elif binding.function:
-            if args or kwargs:
-                result = self.__instantiateCallableWithArgs(binding.function, *args, **kwargs)
-            else:
-                result = self.__instantiateCallableReflective(binding.function)
-
-            # Store the result directly as the singleton instance
-            # We don't automatically invoke factory function results anymore
-            binding.instance = result
-            return binding.instance
-
-        # If neither concrete class nor function is defined
-        else:
-            raise OrionisContainerException(
-                "Cannot resolve singleton binding: neither a concrete class, instance, nor function is defined."
-            )
-
-    def __instantiateConcreteWithArgs(self, concrete: Callable[..., Any], *args, **kwargs) -> Any:
-        """
-        Instantiates a concrete class with the provided arguments.
-
-        Parameters
-        ----------
-        concrete : Callable[..., Any]
-            Class to instantiate.
-        *args : tuple
-            Positional arguments to pass to the constructor.
-        **kwargs : dict
-            Keyword arguments to pass to the constructor.
-
-        Returns
-        -------
-        object
-            A new instance of the specified concrete class.
-        """
-
-        # try to instantiate the concrete class with the provided arguments
-        try:
-
-            # If the concrete is a class, instantiate it directly
-            return concrete(*args, **kwargs)
-
-        except TypeError as e:
-
-            # If instantiation fails, use ReflectionConcrete to get class name and constructor signature
-            rf_concrete = ReflectionConcrete(concrete)
-            class_name = rf_concrete.getClassName()
-            signature = rf_concrete.getConstructorSignature()
-
-            # Raise an exception with detailed information about the failure
-            raise OrionisContainerException(
-                f"Failed to instantiate [{class_name}] with the provided arguments: {e}\n"
-                f"Expected constructor signature: [{signature}]"
-            ) from e
-
-    def __instantiateCallableWithArgs(self, fn: Callable[..., Any], *args, **kwargs) -> Any:
-        """
-        Invokes a callable with the provided arguments.
-
-        Parameters
-        ----------
-        fn : Callable[..., Any]
-            The callable to invoke.
-        *args : tuple
-            Positional arguments to pass to the callable.
-        **kwargs : dict
-            Keyword arguments to pass to the callable.
-
-        Returns
-        -------
-        Any
-            The result of the callable.
-        """
-
-        # Try to invoke the callable with the provided arguments
-        try:
-
-            # If the callable is a function, invoke it directly
-            return fn(*args, **kwargs)
-
-        except TypeError as e:
-
-            # If invocation fails, use ReflectionCallable to get function name and signature
-            rf_callable = ReflectionCallable(fn)
-            function_name = rf_callable.getName()
-            signature = rf_callable.getSignature()
-
-            # Raise an exception with detailed information about the failure
-            raise OrionisContainerException(
-                f"Failed to invoke function [{function_name}] with the provided arguments: {e}\n"
-                f"Expected function signature: [{signature}]"
-            ) from e
-
-    def __instantiateConcreteReflective(self, concrete: Callable[..., Any]) -> Any:
-        """
-        Instantiates a concrete class reflectively, resolving its dependencies from the container.
-
-        Parameters
-        ----------
-        concrete : Callable[..., Any]
-            The concrete class to instantiate.
+        # Get the binding for the requested abstract type or alias
+        binding = self.getBinding(abstract_or_alias)
 
-        Returns
-        -------
-        Any
-            A new instance of the concrete class.
-        """
-        # Resolve dependencies for the concrete class
-        params = self.__resolveDependencies(concrete, is_class=True)
-
-        # Instantiate the concrete class with resolved dependencies
-        return concrete(**params)
-
-    def __instantiateCallableReflective(self, fn: Callable[..., Any]) -> Any:
-        """
-        Invokes a callable reflectively, resolving its dependencies from the container.
-
-        Parameters
-        ----------
-        fn : Callable[..., Any]
-            The callable to invoke.
-
-        Returns
-        -------
-        Any
-            The result of the callable.
-        """
-
-        # Resolve dependencies for the callable
-        params = self.__resolveDependencies(fn, is_class=False)
-
-        # Invoke the callable with resolved dependencies
-        return fn(**params)
-
-    def __resolveDependencies(
-        self,
-        target: Callable[..., Any],
-        *,
-        is_class: bool = False
-    ) -> dict:
-        """
-        Resolves dependencies for a target callable or class.
-
-        Parameters
-        ----------
-        target : Callable[..., Any]
-            The target callable or class whose dependencies to resolve.
-        is_class : bool, optional
-            Whether the target is a class (True) or a callable (False).
-
-        Returns
-        -------
-        dict
-            A dictionary of resolved dependencies.
-        """
-        try:
-
-            # Use ReflectionConcrete for classes and ReflectionCallable for callables
-            if is_class:
-                reflection = ReflectionConcrete(target)
-                dependencies = reflection.getConstructorDependencies()
-                name = reflection.getClassName()
-
-            # If the target is a callable, use ReflectionCallable
-            else:
-                reflection = ReflectionCallable(target)
-                dependencies = reflection.getDependencies()
-                name = reflection.getName()
-
-            # Check for unresolved dependencies
-            if dependencies.unresolved:
-                unresolved_args = ', '.join(dependencies.unresolved)
-                raise OrionisContainerException(
-                    f"Cannot resolve '{name}' because the following required arguments are missing: [{unresolved_args}]."
-                )
-
-            # Resolve dependencies
-            params = {}
-            for param_name, dep in dependencies.resolved.items():
-
-                # If the dependency is a ResolvedDependency, resolve it
-                if isinstance(dep, ResolvedDependency):
-
-                    # If the dependency is a built-in type, raise an exception
-                    if dep.module_name == 'builtins':
-                        raise OrionisContainerException(
-                            f"Cannot resolve '{name}' because parameter '{param_name}' depends on built-in type '{dep.type.__name__}'."
-                        )
-
-                    # Try to resolve from container
-                    service = self.__getFirstService([dep.type, dep.full_class_path])
-                    if service:
-                        params[param_name] = self.make(service.alias)
-
-                    # Try to instantiate directly if it's a concrete class
-                    elif ReflectionConcrete.isConcreteClass(dep.type):
-                        params[param_name] = dep.type(**self.__resolveDependencies(dep.type, is_class=True))
-
-                    # Try to call directly if it's a callable
-                    elif callable(dep.type) and not isinstance(dep.type, type):
-                        params[param_name] = dep.type(**self.__resolveDependencies(dep.type, is_class=False))
-
-                    # If the dependency cannot be resolved, raise an exception
-                    else:
-                        raise OrionisContainerException(
-                            f"Cannot resolve dependency '{param_name}' of type '{dep.type.__name__}' for '{name}'."
-                        )
-                else:
-                    # Use default value
-                    params[param_name] = dep
-
-            # Return the resolved parameters
-            return params
-
-        except ImportError as e:
-
-            # Extract module name from the error message if possible
-            import_msg = str(e)
-            module_name = target.__module__ if hasattr(target, '__module__') else "unknown module"
-
-            # Check for potential circular import patterns
-            if "circular import" in import_msg.lower() or "cannot import name" in import_msg.lower():
-                raise OrionisContainerException(
-                    f"Circular import detected while resolving dependencies for '{target.__name__}' in module '{module_name}'.\n"
-                    f"This typically happens when two modules import each other. Consider:\n"
-                    f"1. Restructuring your code to avoid circular dependencies\n"
-                    f"2. Using delayed imports inside methods rather than at module level\n"
-                    f"3. Using dependency injection to break the cycle\n"
-                    f"Original error: {import_msg}"
-                ) from e
-            else:
-                raise OrionisContainerException(
-                    f"Import error while resolving dependencies for '{target.__name__}' in module '{module_name}':\n"
-                    f"{import_msg}"
-                ) from e
-
-        except Exception as e:
-
-            # Get more context about where the error occurred
-            target_type = "class" if isinstance(target, type) else "function"
-            target_name = target.__name__ if hasattr(target, '__name__') else str(target)
-            module_name = target.__module__ if hasattr(target, '__module__') else "unknown module"
-
-            raise OrionisContainerException(
-                f"Error resolving dependencies for {target_type} '{target_name}' in '{module_name}':\n"
-                f"{str(e)}\n"
-                f"Check that all dependencies are properly registered in the container."
-            ) from e
+        # Resolve the binding using the Resolver class
+        return Resolver(self).resolve(
+            binding,
+            *args,
+            **kwargs
+        )

orionis/container/contracts/container.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Any, Callable
 from orionis.container.enums.lifetimes import Lifetime
+from orionis.container.entities.binding import Binding
 
 class IContainer(ABC):
     """
@@ -18,7 +19,7 @@ class IContainer(ABC):
         enforce_decoupling: bool = False
     ) -> bool:
         """
-        Register a service as a singleton.
+        Registers a service with a singleton lifetime.
 
         Parameters
         ----------
@@ -27,7 +28,7 @@ class IContainer(ABC):
         concrete : Callable[..., Any]
             The concrete implementation to associate with the abstract type.
         alias : str, optional
-            An alternative name to register the service under.
+            An alternative name to register the service under. If not provided, the abstract's class name is used.
         enforce_decoupling : bool, optional
             Whether to enforce that concrete is not a subclass of abstract.
 
@@ -48,7 +49,7 @@ class IContainer(ABC):
         enforce_decoupling: bool = False
     ) -> bool:
         """
-        Register a service as transient.
+        Registers a service with a transient lifetime.
 
         Parameters
         ----------
@@ -57,7 +58,7 @@ class IContainer(ABC):
         concrete : Callable[..., Any]
             The concrete implementation to associate with the abstract type.
         alias : str, optional
-            An alternative name to register the service under.
+            An alternative name to register the service under. If not provided, the abstract's class name is used.
         enforce_decoupling : bool, optional
             Whether to enforce that concrete is not a subclass of abstract.
 
@@ -78,7 +79,7 @@ class IContainer(ABC):
         enforce_decoupling: bool = False
     ) -> bool:
         """
-        Register a service as scoped.
+        Registers a service with a scoped lifetime.
 
         Parameters
         ----------
@@ -87,7 +88,7 @@ class IContainer(ABC):
         concrete : Callable[..., Any]
             The concrete implementation to associate with the abstract type.
         alias : str, optional
-            An alternative name to register the service under.
+            An alternative name to register the service under. If not provided, the abstract's class name is used.
         enforce_decoupling : bool, optional
             Whether to enforce that concrete is not a subclass of abstract.
 
@@ -108,7 +109,7 @@ class IContainer(ABC):
         enforce_decoupling: bool = False
     ) -> bool:
         """
-        Register an instance of a service.
+        Registers an instance of a class or interface in the container.
 
         Parameters
         ----------
@@ -117,7 +118,8 @@ class IContainer(ABC):
         instance : Any
             The concrete instance to register.
         alias : str, optional
-            An optional alias to register the instance under.
+            An optional alias to register the instance under. If not provided,
+            the abstract's `__name__` attribute will be used as the alias if available.
         enforce_decoupling : bool, optional
             Whether to enforce that instance's class is not a subclass of abstract.
 
@@ -137,7 +139,7 @@ class IContainer(ABC):
         lifetime: Lifetime = Lifetime.TRANSIENT
     ) -> bool:
         """
-        Register a function as a service.
+        Registers a function or factory under a given alias.
 
         Parameters
         ----------
@@ -163,16 +165,16 @@ class IContainer(ABC):
         **kwargs: dict
     ) -> Any:
         """
-        Resolve a service from the container.
+        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.
+            Positional arguments to pass to the constructor of the resolved service.
         **kwargs : dict
-            Keyword arguments to pass to the constructor.
+            Keyword arguments to pass to the constructor of the resolved service.
 
         Returns
         -------
@@ -187,16 +189,60 @@ class IContainer(ABC):
         abstract_or_alias: Any
     ) -> bool:
         """
-        Check if a service is registered in the container.
+        Checks if a service (by abstract type or alias) is registered in the container.
 
         Parameters
         ----------
         abstract_or_alias : Any
-            The abstract class, interface, or alias (str) to check.
+            The abstract class, interface, or alias (str) to check for registration.
 
         Returns
         -------
         bool
-            True if the service is registered, False otherwise.
+            True if the service is registered (either as an abstract type or alias), False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def getBinding(
+        self,
+        abstract_or_alias: Any
+    ) -> Binding:
+        """
+        Retrieves the binding for the requested abstract type or alias.
+
+        Parameters
+        ----------
+        abstract_or_alias : Any
+            The abstract class, interface, or alias (str) to retrieve.
+
+        Returns
+        -------
+        Binding
+            The binding associated with the requested abstract type or alias.
+        """
+        pass
+
+    @abstractmethod
+    def drop(
+        self,
+        abstract: Callable[..., Any] = None,
+        alias: str = None
+    ) -> None:
+        """
+        Drops a service from the container by removing its bindings and aliases.
+
+        Warning
+        -------
+        Using this method irresponsibly can severely damage the system's logic.
+        Only use it when you are certain about the consequences, as removing
+        critical services may lead to system failures and unexpected behavior.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any], optional
+            The abstract type or interface to be removed from the container.
+        alias : str, optional
+            The alias of the service to be removed.
         """
         pass

orionis/container/resolver.py

@@ -1,7 +1,11 @@
+from typing import Any, Callable
 from orionis.container.contracts.container import IContainer
 from orionis.container.entities.binding import Binding
 from orionis.container.enums.lifetimes import Lifetime
-
+from orionis.container.exceptions.container_exception import OrionisContainerException
+from orionis.services.introspection.callables.reflection_callable import ReflectionCallable
+from orionis.services.introspection.concretes.reflection_concrete import ReflectionConcrete
+from orionis.services.introspection.dependencies.entities.resolved_dependencies import ResolvedDependency
 
 class Resolver:
     """
@@ -10,19 +14,391 @@ class Resolver:
 
     def __init__(
         self,
-        container:IContainer,
-        lifetime:Lifetime
+        container:IContainer
     ):
+        """
+        Initialize the resolver.
+
+        This method initializes the resolver with a reference to the container.
+
+        Parameters
+        ----------
+        container : IContainer
+            The container instance that this resolver will use to resolve dependencies.
+        """
         self.container = container
-        self.lifetime = lifetime
 
-    def transient(
+    def resolve(
         self,
         binding:Binding,
         *args,
         **kwargs
     ):
         """
-        Register a transient service.
+        Resolves an instance from a binding.
+        This method resolves an instance based on the binding's lifetime and type.
+        It delegates to specific resolution methods based on the lifetime (transient, singleton, or scoped).
+        Args:
+            binding (Binding): The binding to resolve.
+            *args: Additional positional arguments to pass to the constructor.
+            **kwargs: 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 scoped lifetime resolution is attempted (not yet implemented).
+        """
+
+        # Ensure the binding is an instance of Binding
+        if not isinstance(binding, Binding):
+            raise OrionisContainerException(
+                "The binding must be an instance of Binding."
+            )
+
+        # Handle based on binding type and lifetime
+        if binding.lifetime == Lifetime.TRANSIENT:
+            return self.__resolveTransient(binding, *args, **kwargs)
+        elif binding.lifetime == Lifetime.SINGLETON:
+            return self.__resolveSingleton(binding, *args, **kwargs)
+        elif binding.lifetime == Lifetime.SCOPED:
+            # TODO: Implement scoped lifetime resolution
+            raise OrionisContainerException(
+                "Scoped lifetime resolution is not yet implemented."
+            )
+
+    def __resolveTransient(self, binding: Binding, *args, **kwargs) -> Any:
+        """
+        Resolves a service with transient lifetime.
+
+        Parameters
+        ----------
+        binding : Binding
+            The binding to resolve.
+        *args : tuple
+            Positional arguments to pass to the constructor.
+        **kwargs : dict
+            Keyword arguments to pass to the constructor.
+
+        Returns
+        -------
+        Any
+            A new instance of the requested service.
+        """
+
+        # Check if the binding has a concrete class or function defined
+        if binding.concrete:
+            if args or kwargs:
+                return self.__instantiateConcreteWithArgs(binding.concrete, *args, **kwargs)
+            else:
+                return self.__instantiateConcreteReflective(binding.concrete)
+
+        # If the binding has a function defined
+        elif binding.function:
+            if args or kwargs:
+                return self.__instantiateCallableWithArgs(binding.function, *args, **kwargs)
+            else:
+                return self.__instantiateCallableReflective(binding.function)
+
+        # If neither concrete class nor function is defined
+        else:
+            raise OrionisContainerException(
+                "Cannot resolve transient binding: neither a concrete class nor a function is defined."
+            )
+
+    def __resolveSingleton(self, binding: Binding, *args, **kwargs) -> Any:
+        """
+        Resolves a service with singleton lifetime.
+
+        Parameters
+        ----------
+        binding : Binding
+            The binding to resolve.
+        *args : tuple
+            Positional arguments to pass to the constructor (only used if instance doesn't exist yet).
+        **kwargs : dict
+            Keyword arguments to pass to the constructor (only used if instance doesn't exist yet).
+
+        Returns
+        -------
+        Any
+            The singleton instance of the requested service.
+        """
+        # Return existing instance if available
+        if binding.instance:
+            return binding.instance
+
+        # Create instance if needed
+        if binding.concrete:
+            if args or kwargs:
+                binding.instance = self.__instantiateConcreteWithArgs(binding.concrete, *args, **kwargs)
+            else:
+                binding.instance = self.__instantiateConcreteReflective(binding.concrete)
+            return binding.instance
+
+        # If the binding has a function defined
+        elif binding.function:
+            if args or kwargs:
+                result = self.__instantiateCallableWithArgs(binding.function, *args, **kwargs)
+            else:
+                result = self.__instantiateCallableReflective(binding.function)
+
+            # Store the result directly as the singleton instance
+            # We don't automatically invoke factory function results anymore
+            binding.instance = result
+            return binding.instance
+
+        # If neither concrete class nor function is defined
+        else:
+            raise OrionisContainerException(
+                "Cannot resolve singleton binding: neither a concrete class, instance, nor function is defined."
+            )
+
+    def __instantiateConcreteWithArgs(self, concrete: Callable[..., Any], *args, **kwargs) -> Any:
+        """
+        Instantiates a concrete class with the provided arguments.
+
+        Parameters
+        ----------
+        concrete : Callable[..., Any]
+            Class to instantiate.
+        *args : tuple
+            Positional arguments to pass to the constructor.
+        **kwargs : dict
+            Keyword arguments to pass to the constructor.
+
+        Returns
+        -------
+        object
+            A new instance of the specified concrete class.
+        """
+
+        # try to instantiate the concrete class with the provided arguments
+        try:
+
+            # If the concrete is a class, instantiate it directly
+            return concrete(*args, **kwargs)
+
+        except TypeError as e:
+
+            # If instantiation fails, use ReflectionConcrete to get class name and constructor signature
+            rf_concrete = ReflectionConcrete(concrete)
+            class_name = rf_concrete.getClassName()
+            signature = rf_concrete.getConstructorSignature()
+
+            # Raise an exception with detailed information about the failure
+            raise OrionisContainerException(
+                f"Failed to instantiate [{class_name}] with the provided arguments: {e}\n"
+                f"Expected constructor signature: [{signature}]"
+            ) from e
+
+    def __instantiateCallableWithArgs(self, fn: Callable[..., Any], *args, **kwargs) -> Any:
+        """
+        Invokes a callable with the provided arguments.
+
+        Parameters
+        ----------
+        fn : Callable[..., Any]
+            The callable to invoke.
+        *args : tuple
+            Positional arguments to pass to the callable.
+        **kwargs : dict
+            Keyword arguments to pass to the callable.
+
+        Returns
+        -------
+        Any
+            The result of the callable.
+        """
+
+        # Try to invoke the callable with the provided arguments
+        try:
+
+            # If the callable is a function, invoke it directly
+            return fn(*args, **kwargs)
+
+        except TypeError as e:
+
+            # If invocation fails, use ReflectionCallable to get function name and signature
+            rf_callable = ReflectionCallable(fn)
+            function_name = rf_callable.getName()
+            signature = rf_callable.getSignature()
+
+            # Raise an exception with detailed information about the failure
+            raise OrionisContainerException(
+                f"Failed to invoke function [{function_name}] with the provided arguments: {e}\n"
+                f"Expected function signature: [{signature}]"
+            ) from e
+
+    def __instantiateConcreteReflective(self, concrete: Callable[..., Any]) -> Any:
+        """
+        Instantiates a concrete class reflectively, resolving its dependencies from the container.
+
+        Parameters
+        ----------
+        concrete : Callable[..., Any]
+            The concrete class to instantiate.
+
+        Returns
+        -------
+        Any
+            A new instance of the concrete class.
+        """
+        # Resolve dependencies for the concrete class
+        params = self.__resolveDependencies(concrete, is_class=True)
+
+        # Instantiate the concrete class with resolved dependencies
+        return concrete(**params)
+
+    def __instantiateCallableReflective(self, fn: Callable[..., Any]) -> Any:
+        """
+        Invokes a callable reflectively, resolving its dependencies from the container.
+
+        Parameters
+        ----------
+        fn : Callable[..., Any]
+            The callable to invoke.
+
+        Returns
+        -------
+        Any
+            The result of the callable.
+        """
+
+        # Resolve dependencies for the callable
+        params = self.__resolveDependencies(fn, is_class=False)
+
+        # Invoke the callable with resolved dependencies
+        return fn(**params)
+
+    def __resolveDependencies(
+        self,
+        target: Callable[..., Any],
+        *,
+        is_class: bool = False
+    ) -> dict:
+        """
+        Resolves dependencies for a target callable or class.
+
+        Parameters
+        ----------
+        target : Callable[..., Any]
+            The target callable or class whose dependencies to resolve.
+        is_class : bool, optional
+            Whether the target is a class (True) or a callable (False).
+
+        Returns
+        -------
+        dict
+            A dictionary of resolved dependencies.
         """
-        return self.container.transient(service, implementation, **kwargs)
+        try:
+
+            # Use ReflectionConcrete for classes and ReflectionCallable for callables
+            if is_class:
+                reflection = ReflectionConcrete(target)
+                dependencies = reflection.getConstructorDependencies()
+                name = reflection.getClassName()
+
+            # If the target is a callable, use ReflectionCallable
+            else:
+                reflection = ReflectionCallable(target)
+                dependencies = reflection.getDependencies()
+                name = reflection.getName()
+
+            # Check for unresolved dependencies
+            if dependencies.unresolved:
+                unresolved_args = ', '.join(dependencies.unresolved)
+                raise OrionisContainerException(
+                    f"Cannot resolve '{name}' because the following required arguments are missing: [{unresolved_args}]."
+                )
+
+            # Resolve dependencies
+            params = {}
+            for param_name, dep in dependencies.resolved.items():
+
+                # If the dependency is a ResolvedDependency, resolve it
+                if isinstance(dep, ResolvedDependency):
+
+                    # If the dependency is a built-in type, raise an exception
+                    if dep.module_name == 'builtins':
+                        raise OrionisContainerException(
+                            f"Cannot resolve '{name}' because parameter '{param_name}' depends on built-in type '{dep.type.__name__}'."
+                        )
+
+                    # Try to resolve from container using type (Abstract or Interface)
+                    if self.container.bound(dep.type):
+                        params[param_name] = self.resolve(
+                            self.container.getBinding(dep.type)
+                        )
+
+                    # Try to resolve from container using full class path
+                    elif self.container.bound(dep.full_class_path):
+                        params[param_name] = self.resolve(
+                            self.container.getBinding(dep.full_class_path)
+                        )
+
+                    # Try to instantiate directly if it's a concrete class
+                    elif ReflectionConcrete.isConcreteClass(dep.type):
+                        params[param_name] = dep.type(**self.__resolveDependencies(dep.type, is_class=True))
+
+                    # Try to call directly if it's a callable
+                    elif callable(dep.type) and not isinstance(dep.type, type):
+                        params[param_name] = dep.type(**self.__resolveDependencies(dep.type, is_class=False))
+
+                    # If the dependency cannot be resolved, raise an exception
+                    else:
+                        raise OrionisContainerException(
+                            f"Cannot resolve dependency '{param_name}' of type '{dep.type.__name__}' for '{name}'."
+                        )
+                else:
+                    # Use default value
+                    params[param_name] = dep
+
+            # Return the resolved parameters
+            return params
+
+        except ImportError as e:
+
+            # Get target name safely
+            target_name = getattr(target, '__name__', str(target))
+            module_name = getattr(target, '__module__', "unknown module")
+
+            # Improved circular import detection with more helpful guidance
+            if "circular import" in str(e).lower() or "cannot import name" in str(e).lower():
+                raise OrionisContainerException(
+                    f"Circular import detected while resolving dependencies for '{target_name}' in module '{module_name}'.\n"
+                    f"This typically happens when two modules import each other. Consider:\n"
+                    f"1. Restructuring your code to avoid circular dependencies\n"
+                    f"2. Using delayed imports inside methods rather than at module level\n"
+                    f"3. Using dependency injection to break the cycle\n"
+                    f"Original error: {str(e)}"
+                ) from e
+            else:
+                raise OrionisContainerException(
+                    f"Import error while resolving dependencies for '{target_name}' in module '{module_name}':\n"
+                    f"{str(e)}"
+                ) from e
+
+        except Exception as e:
+
+            # More robust attribute extraction with fallbacks
+            target_type = "class" if isinstance(target, type) else "function"
+            target_name = getattr(target, '__name__', str(target))
+            module_name = getattr(target, '__module__', "unknown module")
+
+            # More detailed error message with context about the failure
+            error_msg = (
+                f"Error resolving dependencies for {target_type} '{target_name}' in '{module_name}':\n"
+                f"{str(e)}\n"
+            )
+
+            # Add specific guidance based on error type
+            if isinstance(e, TypeError):
+                error_msg += "This may be caused by incompatible argument types or missing required parameters."
+            elif isinstance(e, AttributeError):
+                error_msg += "This may be caused by accessing undefined attributes in the dependency chain."
+            error_msg += "\nCheck that all dependencies are properly registered in the container."
+
+            # Raise a more informative exception
+            raise OrionisContainerException(error_msg) from e
+

orionis/container/validators/lifetime.py

@@ -0,0 +1,53 @@
+from typing import Any, Union
+from orionis.container.enums.lifetimes import Lifetime
+from orionis.container.exceptions.type_error_exception import OrionisContainerTypeError
+
+class __LifetimeValidator:
+    """
+    Validator that checks if a value is a valid lifetime and converts string representations
+    to Lifetime enum values.
+    """
+
+    def __call__(self, lifetime: Union[str, Lifetime, Any]) -> Lifetime:
+        """
+        Validates and normalizes the provided lifetime value.
+
+        Parameters
+        ----------
+        lifetime : Union[str, Lifetime, Any]
+            The lifetime value to validate. Can be a Lifetime enum or a string
+            representing a valid lifetime.
+
+        Returns
+        -------
+        Lifetime
+            The validated Lifetime enum value.
+
+        Raises
+        ------
+        OrionisContainerTypeError
+            If the value is not a valid Lifetime enum or string representation,
+            or if the string doesn't match any valid Lifetime value.
+        """
+        # Already a Lifetime enum
+        if isinstance(lifetime, Lifetime):
+            return lifetime
+
+        # String that might represent a Lifetime
+        if isinstance(lifetime, str):
+            lifetime_key = lifetime.strip().upper()
+            if lifetime_key in Lifetime.__members__:
+                return Lifetime[lifetime_key]
+
+            valid_options = ', '.join(Lifetime.__members__.keys())
+            raise OrionisContainerTypeError(
+                f"Invalid lifetime '{lifetime}'. Valid options are: {valid_options}."
+            )
+
+        # Invalid type
+        raise OrionisContainerTypeError(
+            f"Lifetime must be of type str or Lifetime enum, got {type(lifetime).__name__}."
+        )
+
+# Exported singleton instance
+LifetimeValidator = __LifetimeValidator()

orionis/metadata/framework.py

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

{orionis-0.320.0.dist-info → orionis-0.321.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.320.0
+Version: 0.321.0
 Summary: Orionis Framework – Elegant, Fast, and Powerful.
 Home-page: https://github.com/orionis-framework/framework
 Author: Raul Mauricio Uñate Castro

{orionis-0.320.0.dist-info → orionis-0.321.0.dist-info}/RECORD

@@ -135,9 +135,9 @@ orionis/console/output/console.py,sha256=TE_Hl720ADd82dbERFSWhkoQRukDQZmETSw4nkw
 orionis/console/output/executor.py,sha256=bdvkzW2-buy0BPpy2r5qUGrRFW2Ay6k-5rSeHb0gQ3o,3352
 orionis/console/output/progress_bar.py,sha256=vFy582z6VJS46LV6tuyrmr9qvdVeTEtw3hyNcEHezeg,3088
 orionis/console/output/styles.py,sha256=6a4oQCOBOKMh2ARdeq5GlIskJ3wjiylYmh66tUKKmpQ,4053
-orionis/container/container.py,sha256=HHEXnObv1Q_022dfGpTOx6cwyRPa7ooD8FfqJ_cDCro,37291
-orionis/container/resolver.py,sha256=9nojqjrYYXw2kQUzyuLkHs-os5dDxq6ntZ8e8IbYIu0,704
-orionis/container/contracts/container.py,sha256=LkZ5til_3Um8ctCVTwuO36HkysL59saKwUzXR5cWUBs,5750
+orionis/container/container.py,sha256=eBVQMzfSvXcxrdm-0hq0gmXZzxf3uabIcxbGVvGZmIo,22342
+orionis/container/resolver.py,sha256=iuyTWCnCqWXQCtWvFXPdS9cR_g3Q58_wjHVn0Yg0YNM,16209
+orionis/container/contracts/container.py,sha256=ksMn6ZLnFkIxd9_hbUGz3OpHzaYTA5izcDtH959kOow,7603
 orionis/container/entities/binding.py,sha256=Qp6Lf4XUDp2NjqXDAC2lzvhOFQWiBDKiGFcKfwb4axw,4342
 orionis/container/enums/lifetimes.py,sha256=RqQmugMIB1Ev_j_vFLcWorndm-to7xg4stQ7yKFDdDw,190
 orionis/container/exceptions/container_exception.py,sha256=goTDEwC70xTMD2qppN8KV-xyR0Nps218OD4D1LZ2-3s,470
@@ -152,6 +152,7 @@ orionis/container/validators/is_instance.py,sha256=vUwWIMeG1zLMsGX9GyoOU-LZtCgqB
 orionis/container/validators/is_not_subclass.py,sha256=-iZw5ZCYnQtlU-xPO-o7lUj5DxPkN0G67-bLbLVhwtw,1167
 orionis/container/validators/is_subclass.py,sha256=O2aF0KLg5ZnDutKQ1xDvet34kentftlqgEkRNvumCoM,1135
 orionis/container/validators/is_valid_alias.py,sha256=avm6uz-huVi_kRov4BksSToslIHQfz-MLynjkzhdSRM,1246
+orionis/container/validators/lifetime.py,sha256=78o7BHBCRReG8vnF0gW2RUf6m6wwMhr7w4VA6F2B46A,1865
 orionis/foundation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/foundation/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/foundation/config/startup.py,sha256=JKAH2ZRhlAZgkD2w11LR1-TVktfjSH9cHo3PsZXOLrg,8275
@@ -243,7 +244,7 @@ orionis/foundation/contracts/config.py,sha256=Rpz6U6t8OXHO9JJKSTnCimytXE-tfCB-1i
 orionis/foundation/exceptions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/foundation/exceptions/integrity.py,sha256=mc4pL1UMoYRHEmphnpW2oGk5URhu7DJRREyzHaV-cs8,472
 orionis/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/metadata/framework.py,sha256=sBQIEDehFdisleRXQSFyOhHx2bVTGjprHNNBI_Famsw,4960
+orionis/metadata/framework.py,sha256=gv-aVbvyQwRvOTPPCJTIwJffZOEd9Ak6L9jdwT46oOE,4960
 orionis/metadata/package.py,sha256=tqLfBRo-w1j_GN4xvzUNFyweWYFS-qhSgAEc-AmCH1M,5452
 orionis/patterns/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/patterns/singleton/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -355,7 +356,7 @@ orionis/test/suite/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuF
 orionis/test/suite/test_unit.py,sha256=MWgW8dRCRyT1XZ5LsbXQ7-KVPReasoXwzEEL1EWWfE4,52190
 orionis/test/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/test/view/render.py,sha256=jXZkbITBknbUwm_mD8bcTiwLDvsFkrO9qrf0ZgPwqxc,4903
-orionis-0.320.0.dist-info/licenses/LICENCE,sha256=-_4cF2EBKuYVS_SQpy1uapq0oJPUU1vl_RUWSy2jJTo,1111
+orionis-0.321.0.dist-info/licenses/LICENCE,sha256=-_4cF2EBKuYVS_SQpy1uapq0oJPUU1vl_RUWSy2jJTo,1111
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/example/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/example/test_example.py,sha256=kvWgiW3ADEZf718dGsMPtDh_rmOSx1ypEInKm7_6ZPQ,601
@@ -456,8 +457,8 @@ tests/support/wrapper/test_services_wrapper_docdict.py,sha256=yeVwl-VcwkWSQYyxZu
 tests/testing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/testing/test_testing_result.py,sha256=MrGK3ZimedL0b5Ydu69Dg8Iul017AzLTm7VPxpXlpfU,4315
 tests/testing/test_testing_unit.py,sha256=DjLBtvVn8B1KlVJNNkstBT8_csA1yeaMqnGrbanN_J4,7438
-orionis-0.320.0.dist-info/METADATA,sha256=J4HkjZk_1Wa2wuK0UZboolNPepT3CA4uflTNQrXlGk0,4772
-orionis-0.320.0.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-orionis-0.320.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
-orionis-0.320.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-orionis-0.320.0.dist-info/RECORD,,
+orionis-0.321.0.dist-info/METADATA,sha256=kQ_DamwqrnAqkqPJQZd6mR4u-U_ERbRLwEw8FqTgTwE,4772
+orionis-0.321.0.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
+orionis-0.321.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
+orionis-0.321.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+orionis-0.321.0.dist-info/RECORD,,