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

orionis/container/container.py

@@ -1,16 +1,26 @@
+import threading
 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.container.exceptions.type_error_exception import OrionisContainerTypeError
+from orionis.container.validators.implements import ImplementsAbstractMethods
+from orionis.container.validators.is_abstract_class import IsAbstractClass
+from orionis.container.validators.is_callable import IsCallable
+from orionis.container.validators.is_concrete_class import IsConcreteClass
+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.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
-import threading
 
-class Container:
+class Container(IContainer):
 
     # Singleton instance of the container.
     # This is a class variable that holds the single instance of the Container class.
@@ -26,7 +36,11 @@ class Container:
     # regardless of how many times the class is instantiated.
     _initialized = False
 
-    def __new__(cls, *args, **kwargs):
+    def __new__(
+        cls,
+        *args,
+        **kwargs
+    ) -> 'Container':
         """
         Creates and returns a singleton instance of the class.
 
@@ -45,339 +59,53 @@ class Container:
         Container
             The singleton instance of the class.
         """
+
+        # Check if the class has an existing instance
         if cls._instance is None:
+
+            # Acquire the lock to ensure thread safety during instance creation
             with cls._lock:
+
+                # If the instance is still None, create a new instance
                 if cls._instance is None:
+
+                    # Call the superclass's __new__ method to create a new instance
                     cls._instance = super(Container, cls).__new__(cls)
+
+        # Return the existing instance of the class
         return cls._instance
 
-    def __init__(self):
+    def __init__(
+        self
+    ) -> None:
         """
         Initializes a new instance of the container.
 
         This constructor sets up the internal dictionaries for bindings and aliases,
         ensuring that these are only initialized once per class. The initialization
         is guarded by the `_initialized` class attribute to prevent redundant setup.
+        The container also registers itself as a service to allow for injection.
 
         Notes
         -----
         - The `__bindings` dictionary is used to store service bindings.
         - The `__aliasses` dictionary is used to store service aliases.
         - Initialization occurs only once per class, regardless of the number of instances.
+        - The container registers itself under the IContainer interface to allow for dependency injection.
         """
+
+        # Check if the class has been initialized
         if not self.__class__._initialized:
+
+            # Initialize the container's internal state
             self.__bindings = {}
             self.__aliasses = {}
-            self.__class__._initialized = True
-
-    def __dropService(
-        self,
-        abstract: Callable[..., Any] = None,
-        alias: str = None
-    ) -> None:
-        """
-        Drops a service from the container.
-
-        Parameters
-        ----------
-        abstract : Callable[..., Any]
-            The abstract type or interface to be removed.
-        alias : str, optional
-            The alias of the service to be removed. If not provided, the service will be removed by its abstract type.
-
-        Raises
-        ------
-        OrionisContainerException
-            If the service does not exist in the container.
-        """
-
-        # If abstract is provided
-        if abstract:
-
-            # Remove the abstract service from the bindings if it exists
-            if abstract in self.__bindings:
-                del self.__bindings[abstract]
-
-            # Remove the default alias (module + class name) from aliases if it exists
-            abs_alias = ReflectionAbstract(abstract).getModuleWithClassName()
-            if abs_alias in self.__aliasses:
-                del self.__aliasses[abs_alias]
-
-        # If a custom alias is provided
-        if alias:
-
-            # Remove it from the aliases dictionary if it exists
-            if alias in self.__aliasses:
-                del self.__aliasses[alias]
-
-            # Remove the binding associated with the alias
-            if alias in self.__bindings:
-                del self.__bindings[alias]
-
-    def __ensureIsCallable(
-        self,
-        value: Any
-    ) -> None:
-        """
-        Ensures that the provided value is callable.
-
-        Parameters
-        ----------
-        value : Any
-            The value to check.
-
-        Raises
-        ------
-        OrionisContainerTypeError
-            If the value is not callable.
-        """
-
-        if not callable(value):
-            raise OrionisContainerTypeError(
-                f"Expected a callable type, but got {type(value).__name__} instead."
-            )
-
-    def __ensureAliasType(
-        self,
-        value: Any
-    ) -> None:
-        """
-        Ensures that the provided value is a valid alias of type str and does not contain invalid characters.
-
-        Parameters
-        ----------
-        value : Any
-            The value to check.
-
-        Raises
-        ------
-        OrionisContainerTypeError
-            If the value is not of type str or contains invalid characters.
-
-        Notes
-        -----
-        This method validates that a given value is a string and does not contain characters
-        that could cause errors when resolving dependencies (e.g., whitespace, special symbols).
-        """
-
-        # Check if the value is a string
-        if not isinstance(value, str):
-            raise OrionisContainerTypeError(
-                f"Expected a string type for alias, but got {type(value).__name__} instead."
-            )
-
-        # Define a set of invalid characters for aliases
-        invalid_chars = set(' \t\n\r\x0b\x0c!@#$%^&*()[]{};:,/<>?\\|`~"\'')
-        if any(char in invalid_chars for char in value):
-            raise OrionisContainerTypeError(
-                f"Alias '{value}' contains invalid characters. "
-                "Aliases must not contain whitespace or special symbols."
-            )
-
-    def __ensureAbstractClass(
-        self,
-        abstract: Callable[..., Any],
-        lifetime: str
-    ) -> None:
-        """
-        Ensures that the provided abstract is an abstract class.
-
-        Parameters
-        ----------
-        abstract : Callable[..., Any]
-            The class intended to represent the abstract type.
-        lifetime : str
-            The service lifetime descriptor, used for error messages.
-
-        Raises
-        ------
-        OrionisContainerTypeError
-            If the abstract class check fails.
-        """
-        try:
-            ReflectionAbstract.ensureIsAbstractClass(abstract)
-        except Exception as e:
-            raise OrionisContainerTypeError(
-                f"Unexpected error registering {lifetime} service: {e}"
-            ) from e
-
-    def __ensureConcreteClass(
-        self,
-        concrete: Callable[..., Any],
-        lifetime: str
-    ) -> None:
-        """
-        Ensures that the provided concrete is a concrete (non-abstract) class.
-
-        Parameters
-        ----------
-        concrete : Callable[..., Any]
-            The class intended to represent the concrete implementation.
-        lifetime : str
-            The service lifetime descriptor, used for error messages.
-
-        Raises
-        ------
-        OrionisContainerTypeError
-            If the concrete class check fails.
-        """
-        try:
-            ReflectionConcrete.ensureIsConcreteClass(concrete)
-        except Exception as e:
-            raise OrionisContainerTypeError(
-                f"Unexpected error registering {lifetime} service: {e}"
-            ) from e
-
-    def __ensureIsSubclass(
-        self,
-        abstract: Callable[..., Any],
-        concrete: Callable[..., Any]
-    ) -> None:
-        """
-        Validates that the concrete class is a subclass of the provided abstract class.
-
-        Parameters
-        ----------
-        abstract : Callable[..., Any]
-            The abstract base class or interface.
-        concrete : Callable[..., Any]
-            The concrete implementation class to check.
-
-        Raises
-        ------
-        OrionisContainerException
-            If the concrete class is NOT a subclass of the abstract class.
-
-        Notes
-        -----
-        This method ensures that the concrete implementation inherits from the abstract class,
-        which is required for proper dependency injection and interface enforcement.
-        """
-        if not issubclass(concrete, abstract):
-            raise OrionisContainerException(
-                "The concrete class must inherit from the provided abstract class. "
-                "Please ensure that the concrete class is a subclass of the specified abstract class."
-            )
-
-    def __ensureIsNotSubclass(
-        self,
-        abstract: Callable[..., Any],
-        concrete: Callable[..., Any]
-    ) -> None:
-        """
-        Validates that the concrete class is NOT a subclass of the provided abstract class.
-
-        Parameters
-        ----------
-        abstract : Callable[..., Any]
-            The abstract base class or interface.
-        concrete : Callable[..., Any]
-            The concrete implementation class to check.
-
-        Raises
-        ------
-        OrionisContainerException
-            If the concrete class IS a subclass of the abstract class.
-
-        Notes
-        -----
-        This method ensures that the concrete implementation does NOT inherit from the abstract class.
-        """
-        if issubclass(concrete, abstract):
-            raise OrionisContainerException(
-                "The concrete class must NOT inherit from the provided abstract class. "
-                "Please ensure that the concrete class is not a subclass of the specified abstract class."
-            )
-
-    def __ensureInstance(
-        self,
-        instance: Any
-    ) -> None:
-        """
-        Ensures that the provided object is a valid instance.
-
-        Parameters
-        ----------
-        instance : Any
-            The object to be validated as an instance.
-
-        Raises
-        ------
-        OrionisContainerTypeError
-            If the provided object is not a valid instance.
-
-        Notes
-        -----
-        This method uses ReflectionInstance to verify that the given object
-        is a proper instance (not a class or abstract type). If the check fails,
-        an OrionisContainerTypeError is raised with a descriptive message.
-        """
-        try:
-            ReflectionInstance.ensureIsInstance(instance)
-        except Exception as e:
-            raise OrionisContainerTypeError(
-                f"Error registering instance: {e}"
-            ) from e
-
-    def __ensureImplementation(
-        self,
-        *,
-        abstract: Callable[..., Any] = None,
-        concrete: Callable[..., Any] = None,
-        instance: Any = None
-    ) -> None:
-        """
-        Ensures that a concrete class or instance implements all abstract methods defined in an abstract class.
-
-        Parameters
-        ----------
-        abstract : Callable[..., Any]
-            The abstract class containing abstract methods.
-        concrete : Callable[..., Any], optional
-            The concrete class that should implement the abstract methods.
-        instance : Any, optional
-            The instance that should implement the abstract methods.
-
-        Raises
-        ------
-        OrionisContainerException
-            If the concrete class or instance does not implement all abstract methods defined in the abstract class.
-
-        Notes
-        -----
-        This method checks that all abstract methods in the given abstract class are implemented
-        in the provided concrete class or instance. If any methods are missing, an exception is raised with
-        details about the missing implementations.
-        """
-        if abstract is None:
-            raise OrionisContainerException("Abstract class must be provided for implementation check.")
-
-        abstract_methods = getattr(abstract, '__abstractmethods__', set())
-        if not abstract_methods:
-            raise OrionisContainerException(
-                f"The abstract class '{abstract.__name__}' does not define any abstract methods. "
-                "An abstract class must have at least one abstract method."
-            )
-
-        target = concrete if concrete is not None else instance
-        if target is None:
-            raise OrionisContainerException("Either concrete class or instance must be provided for implementation check.")
-
-        target_class = target if Reflection.isClass(target) else target.__class__
-        target_name = target_class.__name__
-        abstract_name = abstract.__name__
 
-        not_implemented = []
-        for method in abstract_methods:
-            if not hasattr(target, str(method).replace(f"_{abstract_name}", f"_{target_name}")):
-                not_implemented.append(method)
+            # Set the initialized flag to True to prevent re-initialization
+            self.__class__._initialized = True
 
-        if not_implemented:
-            formatted_methods = "\n  • " + "\n  • ".join(not_implemented)
-            raise OrionisContainerException(
-                f"'{target_name}' does not implement the following abstract methods defined in '{abstract_name}':{formatted_methods}\n"
-                "Please ensure that all abstract methods are implemented."
-            )
+            # Register the container itself as a service
+            self.instance(IContainer, self)
 
     def transient(
         self,
@@ -419,28 +147,28 @@ class Container:
         """
 
         # Ensure that abstract is an abstract class
-        self.__ensureAbstractClass(abstract, Lifetime.TRANSIENT)
+        IsAbstractClass(abstract, Lifetime.TRANSIENT)
 
         # Ensure that concrete is a concrete class
-        self.__ensureConcreteClass(concrete, Lifetime.TRANSIENT)
+        IsConcreteClass(concrete, Lifetime.TRANSIENT)
 
         # Ensure that concrete is NOT a subclass of abstract
         if enforce_decoupling:
-            self.__ensureIsNotSubclass(abstract, concrete)
+            IsNotSubclass(abstract, concrete)
 
         # Validate that concrete is a subclass of abstract
         else:
-            self.__ensureIsSubclass(abstract, concrete)
+            IsSubclass(abstract, concrete)
 
         # Ensure implementation
-        self.__ensureImplementation(
+        ImplementsAbstractMethods(
             abstract=abstract,
             concrete=concrete
         )
 
         # Ensure that the alias is a valid string if provided
         if alias:
-            self.__ensureAliasType(alias)
+            IsValidAlias(alias)
 
         # Extract the module and class name for the alias
         else:
@@ -448,7 +176,7 @@ class Container:
             alias = rf_asbtract.getModuleWithClassName()
 
         # If the service is already registered, drop it
-        self.__dropService(abstract, alias)
+        self.drop(abstract, alias)
 
         # Register the service with transient lifetime
         self.__bindings[abstract] = Binding(
@@ -504,34 +232,34 @@ class Container:
         """
 
         # Ensure that abstract is an abstract class
-        self.__ensureAbstractClass(abstract, Lifetime.SINGLETON)
+        IsAbstractClass(abstract, Lifetime.SINGLETON)
 
         # Ensure that concrete is a concrete class
-        self.__ensureConcreteClass(concrete, Lifetime.SINGLETON)
+        IsConcreteClass(concrete, Lifetime.SINGLETON)
 
         # Ensure that concrete is NOT a subclass of abstract
         if enforce_decoupling:
-            self.__ensureIsNotSubclass(abstract, concrete)
+            IsNotSubclass(abstract, concrete)
 
         # Validate that concrete is a subclass of abstract
         else:
-            self.__ensureIsSubclass(abstract, concrete)
+            IsSubclass(abstract, concrete)
 
         # Ensure implementation
-        self.__ensureImplementation(
+        ImplementsAbstractMethods(
             abstract=abstract,
             concrete=concrete
         )
 
         # Ensure that the alias is a valid string if provided
         if alias:
-            self.__ensureAliasType(alias)
+            IsValidAlias(alias)
         else:
             rf_asbtract = ReflectionAbstract(abstract)
             alias = rf_asbtract.getModuleWithClassName()
 
         # If the service is already registered, drop it
-        self.__dropService(abstract, alias)
+        self.drop(abstract, alias)
 
         # Register the service with singleton lifetime
         self.__bindings[abstract] = Binding(
@@ -587,34 +315,34 @@ class Container:
         """
 
         # Ensure that abstract is an abstract class
-        self.__ensureAbstractClass(abstract, Lifetime.SCOPED)
+        IsAbstractClass(abstract, Lifetime.SCOPED)
 
         # Ensure that concrete is a concrete class
-        self.__ensureConcreteClass(concrete, Lifetime.SCOPED)
+        IsConcreteClass(concrete, Lifetime.SCOPED)
 
         # Ensure that concrete is NOT a subclass of abstract
         if enforce_decoupling:
-            self.__ensureIsNotSubclass(abstract, concrete)
+            IsNotSubclass(abstract, concrete)
 
         # Validate that concrete is a subclass of abstract
         else:
-            self.__ensureIsSubclass(abstract, concrete)
+            IsSubclass(abstract, concrete)
 
         # Ensure implementation
-        self.__ensureImplementation(
+        ImplementsAbstractMethods(
             abstract=abstract,
             concrete=concrete
         )
 
         # Ensure that the alias is a valid string if provided
         if alias:
-            self.__ensureAliasType(alias)
+            IsValidAlias(alias)
         else:
             rf_asbtract = ReflectionAbstract(abstract)
             alias = rf_asbtract.getModuleWithClassName()
 
         # If the service is already registered, drop it
-        self.__dropService(abstract, alias)
+        self.drop(abstract, alias)
 
         # Register the service with scoped lifetime
         self.__bindings[abstract] = Binding(
@@ -668,34 +396,34 @@ class Container:
         """
 
         # Ensure that the abstract is an abstract class
-        self.__ensureAbstractClass(abstract, f"Instance {Lifetime.SINGLETON}")
+        IsAbstractClass(abstract, f"Instance {Lifetime.SINGLETON}")
 
         # Ensure that the instance is a valid instance
-        self.__ensureInstance(instance)
+        IsInstance(instance)
 
         # Ensure that instance is NOT a subclass of abstract
         if enforce_decoupling:
-            self.__ensureIsNotSubclass(abstract, instance.__class__)
+            IsNotSubclass(abstract, instance.__class__)
 
         # Validate that instance is a subclass of abstract
         else:
-            self.__ensureIsSubclass(abstract, instance.__class__)
+            IsSubclass(abstract, instance.__class__)
 
         # Ensure implementation
-        self.__ensureImplementation(
+        ImplementsAbstractMethods(
             abstract=abstract,
             instance=instance
         )
 
         # Ensure that the alias is a valid string if provided
         if alias:
-            self.__ensureAliasType(alias)
+            IsValidAlias(alias)
         else:
             rf_asbtract = ReflectionAbstract(abstract)
             alias = rf_asbtract.getModuleWithClassName()
 
         # If the service is already registered, drop it
-        self.__dropService(abstract, alias)
+        self.drop(abstract, alias)
 
         # Register the instance with the abstract type
         self.__bindings[abstract] = Binding(
@@ -715,7 +443,7 @@ class Container:
     def function(
         self,
         alias: str,
-        function: Callable[..., Any],
+        fn: Callable[..., Any],
         *,
         lifetime: Lifetime = Lifetime.TRANSIENT
     ) -> bool:
@@ -726,7 +454,7 @@ class Container:
         ----------
         alias : str
             The alias to register the function under.
-        function : Callable[..., Any]
+        fn : Callable[..., Any]
             The function or factory to register.
         lifetime : Lifetime, optional
             The lifetime of the function registration (default is TRANSIENT).
@@ -760,13 +488,13 @@ class Container:
                 )
 
         # Ensure that the alias is a valid string
-        self.__ensureAliasType(alias)
+        IsValidAlias(alias)
 
         # Validate that the function is callable
-        self.__ensureIsCallable(function)
+        IsCallable(fn)
 
         # Inspect the function signature
-        params = ReflectionCallable(function).getDependencies()
+        params = ReflectionCallable(fn).getDependencies()
 
         # If the function requires arguments, only allow TRANSIENT
         if (len(params.resolved) + len(params.unresolved)) > 0 and lifetime != Lifetime.TRANSIENT:
@@ -775,11 +503,11 @@ class Container:
             )
 
         # If the service is already registered, drop it
-        self.__dropService(None, alias)
+        self.drop(None, alias)
 
         # Register the function with the specified alias and lifetime
         self.__bindings[alias] = Binding(
-            function=function,
+            function=fn,
             lifetime=lifetime,
             alias=alias
         )
@@ -816,11 +544,104 @@ class Container:
             or abstract_or_alias in self.__aliasses
         )
 
+    def __getService(
+        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.
+        """
+        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,
+        alias: str = None
+    ) -> None:
+        """
+        Drops a service from the container by removing its bindings and aliases.
+        This method allows removing registered services from the dependency injection container,
+        either by their abstract type or by their alias. When a service is dropped,
+        all its bindings and aliases are removed from the container.
+
+        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.
+        abstract : Callable[..., Any], optional
+            The abstract type or interface to be removed from the container.
+            If provided, both the binding and the default alias for this type will be removed.
+            The alias of the service to be removed. If provided, both the alias entry
+            and any associated binding will be removed.
+
+        Notes
+        -----
+        At least one parameter (abstract or alias) must be provided for the method to take effect.
+        If both are provided, both will be processed independently.
+        """
+
+        # If abstract is provided
+        if abstract:
+
+            # Remove the abstract service from the bindings if it exists
+            if abstract in self.__bindings:
+                del self.__bindings[abstract]
+
+            # Remove the default alias (module + class name) from aliases if it exists
+            abs_alias = ReflectionAbstract(abstract).getModuleWithClassName()
+            if abs_alias in self.__aliasses:
+                del self.__aliasses[abs_alias]
+
+        # If a custom alias is provided
+        if alias:
+
+            # Remove it from the aliases dictionary if it exists
+            if alias in self.__aliasses:
+                del self.__aliasses[alias]
+
+            # Remove the binding associated with the alias
+            if alias in self.__bindings:
+                del self.__bindings[alias]
+
     def make(
         self,
         abstract_or_alias: Any,
-        *args,
-        **kwargs
+        *args: tuple,
+        **kwargs: dict
     ) -> Any:
         """
         Resolves and returns an instance of the requested service.
@@ -844,11 +665,341 @@ class Container:
         OrionisContainerException
             If the requested service is not registered in the container.
         """
-        if not self.bound(abstract_or_alias):
+        # 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:
             raise OrionisContainerException(
                 f"The requested service '{abstract_or_alias}' is not registered in the container."
             )
 
-        binding = self.__bindings.get(abstract_or_alias) or self.__aliasses.get(abstract_or_alias)
+        # 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.
 
-        print(binding)
+        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.
+        """
+        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