orionis 0.320.0__tar.gz → 0.321.0__tar.gz

{orionis-0.320.0/orionis.egg-info → orionis-0.321.0}/PKG-INFO

@@ -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 → orionis-0.321.0}/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-0.320.0 → orionis-0.321.0}/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