orionis 0.139.0__py3-none-any.whl → 0.151.0__py3-none-any.whl

orionis/luminate/container/container_integrity.py

@@ -0,0 +1,235 @@
+import re
+import inspect
+from abc import ABC
+from typing import Any, Callable, Type
+from orionis.luminate.container.exception import OrionisContainerValueError, OrionisContainerTypeError
+from orionis.luminate.contracts.container.container_integrity import IContainerIntegrity
+
+class ContainerIntegrity(IContainerIntegrity):
+
+    @staticmethod
+    def ensureImplementation(abstract: Type, concrete: Type) -> None:
+        """
+        Verify at runtime if `concrete` implements all methods of `abstract`.
+
+        :param abstract: Abstract class or interface.
+        :param concrete: Concrete class that should implement the abstract class.
+        :raises TypeError: If `concrete` does not implement all methods of `abstract`.
+        """
+        # Get public methods of the interface (excluding magic methods)
+        interface_methods = {
+            name for name, func in inspect.getmembers(abstract, predicate=inspect.isfunction)
+            if not name.startswith("_")
+        }
+
+        # Get public methods of the concrete class
+        class_methods = {
+            name for name, func in inspect.getmembers(concrete, predicate=inspect.isfunction)
+            if not name.startswith("_")
+        }
+
+        # Verify that all interface methods are in the concrete class
+        if not interface_methods.issubset(class_methods):
+            missing_methods = interface_methods - class_methods
+            raise OrionisContainerTypeError(f"{concrete.__name__} does not implement the required methods of {abstract.__name__}: {missing_methods}")
+
+
+    @staticmethod
+    def ensureIsAbstract(abstract: Callable[..., Any]) -> None:
+        """
+        Ensure that the given abstract is a valid abstract class.
+
+        :param abstract: Class to check
+        :raises OrionisContainerValueError: If the class is not a valid abstract interface
+        """
+        if not isinstance(abstract, type) or not issubclass(abstract, ABC) or abstract is ABC:
+            raise OrionisContainerValueError("The provided class must inherit from ABC and not be ABC itself.")
+
+        if not any(getattr(attr, "__isabstractmethod__", False) for attr in abstract.__dict__.values()):
+            raise OrionisContainerValueError("The provided class must define at least one abstract method.")
+
+    @staticmethod
+    def ensureIsCallable(concrete: Callable[..., Any]) -> None:
+        """
+        Ensure that the given implementation is callable or instantiable.
+
+        Parameters
+        ----------
+        concrete : Callable[..., Any]
+            The implementation to check.
+
+        Raises
+        ------
+        OrionisContainerTypeError
+            If the implementation is not callable.
+        """
+        if not callable(concrete):
+            raise OrionisContainerTypeError(f"The implementation '{str(concrete)}' must be callable or an instantiable class.")
+
+    @staticmethod
+    def ensureIsInstance(instance: Any) -> None:
+        """
+        Ensure that the given instance is a valid object.
+
+        Parameters
+        ----------
+        instance : Any
+            The instance to check.
+
+        Raises
+        ------
+        OrionisContainerValueError
+            If the instance is not a valid object.
+        """
+        if not isinstance(instance, object):
+            raise OrionisContainerValueError(f"The instance '{str(instance)}' must be a valid object.")
+
+        module = type(instance).__module__
+        if module in ['builtins', 'abc']:
+            raise OrionisContainerValueError(f"The instance '{str(instance)}' is not a valid user-defined object. It belongs to the '{module}' module.")
+
+    @staticmethod
+    def ensureNotMain(concrete: Callable[..., Any]) -> str:
+        """
+        Ensure that a class is not defined in the main script.
+
+        Parameters
+        ----------
+        concrete : Callable[..., Any]
+            The class or function to check.
+
+        Returns
+        -------
+        str
+            The fully qualified name of the class.
+
+        Raises
+        ------
+        OrionisContainerValueError
+            If the class is defined in the main module.
+        """
+        if concrete.__module__ == "__main__":
+            raise OrionisContainerValueError("Cannot register a class from the (__main__) module in the container.")
+
+    @staticmethod
+    def ensureIsAlias(name: str) -> bool:
+        """
+        Ensure that the given alias name is a valid string, with no special characters or spaces, 
+        and it is not a primitive type.
+
+        Parameters
+        ----------
+        name : str
+            The alias name to check.
+
+        Raises
+        ------
+        OrionisContainerValueError
+            If the alias is invalid.
+        """
+        if not isinstance(name, str):
+            raise OrionisContainerValueError(f"The alias '{name}' must be a string.")
+
+        if not re.match(r'^[a-zA-Z0-9]+$', name):
+            raise OrionisContainerValueError(f"The alias '{name}' can only contain letters and numbers, without spaces or special characters.")
+
+        if name in {
+            int, "int",
+            float, "float",
+            str, "str",
+            bool, "bool",
+            bytes, "bytes",
+            type(None), "None",
+            complex, "complex",
+            list, "list",
+            tuple, "tuple",
+            dict, "dict",
+            set, "set",
+            frozenset, "frozenset"
+        }:
+            raise OrionisContainerValueError(f"The alias '{name}' cannot be a primitive type.")
+
+    @staticmethod
+    def isAlias(name: str) -> bool:
+        """
+        Check if the given alias name is a valid string, with no special characters or spaces,
+        and it is not a primitive type.
+
+        Parameters
+        ----------
+        name : str
+            The alias name to check.
+
+        Returns
+        -------
+        bool
+            True if the alias is valid, False otherwise.
+        """
+        try:
+            ContainerIntegrity.ensureIsAlias(name)
+            return True
+        except OrionisContainerValueError:
+            return False
+
+    @staticmethod
+    def isCallable(concrete: Callable[..., Any]) -> bool:
+        """
+        Check if the given implementation is callable or instantiable.
+
+        Parameters
+        ----------
+        concrete : Callable[..., Any]
+            The implementation to check.
+
+        Returns
+        -------
+        bool
+            True if the implementation is callable, False otherwise.
+        """
+        try:
+            ContainerIntegrity.ensureIsCallable(concrete)
+            return True
+        except OrionisContainerTypeError:
+            return False
+
+    @staticmethod
+    def isInstance(instance: Any) -> bool:
+        """
+        Check if the given instance is a valid object.
+
+        Parameters
+        ----------
+        instance : Any
+            The instance to check.
+
+        Returns
+        -------
+        bool
+            True if the instance is valid, False otherwise.
+        """
+        try:
+            ContainerIntegrity.ensureIsInstance(instance)
+            return True
+        except OrionisContainerValueError:
+            return False
+
+    @staticmethod
+    def isAbstract(abstract: Callable[..., Any]) -> bool:
+        """
+        Check if the given abstract is a valid abstract class.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any]
+            The class to check.
+
+        Returns
+        -------
+        bool
+            True if the class is a valid abstract interface, False otherwise.
+        """
+        try:
+            ContainerIntegrity.ensureIsAbstract(abstract)
+            return True
+        except OrionisContainerValueError:
+            return False

orionis/luminate/container/lifetimes.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+class Lifetime(Enum):
+    """Defines the lifecycle types for dependency injection."""
+
+    # Creates a new instance every time it is requested
+    TRANSIENT = "transient"
+
+    # A single instance is shared throughout the application
+    SINGLETON = "singleton"
+
+    # A new instance is created per request or context
+    SCOPED = "scoped"

orionis/luminate/contracts/console/{i_parser.py → parser.py}

@@ -2,7 +2,6 @@ from abc import ABC, abstractmethod
 from typing import List, Tuple, Dict, Any
 import argparse
 
-
 class IParser(ABC):
     """
     Interface for a command-line argument parser.

orionis/luminate/contracts/container/container.py

@@ -0,0 +1,346 @@
+from abc import ABC, abstractmethod
+
+class IContainer(ABC):
+
+    @abstractmethod
+    def bind(self, abstract, concrete, lifetime):
+        """
+        Binds an abstract type to a concrete implementation with a specified lifetime.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any]
+            The abstract base type or alias to be bound.
+        concrete : Callable[..., Any]
+            The concrete implementation to associate with the abstract type.
+        lifetime : str
+            The lifecycle of the binding. Must be one of 'transient', 'scoped', or 'singleton'.
+
+        Raises
+        ------
+        OrionisContainerValueError
+            If an invalid lifetime is provided or the concrete implementation is None.
+
+        Examples
+        --------
+        >>> container.bind(MyService, MyServiceImplementation, "singleton")
+        """
+        pass
+
+    @abstractmethod
+    def transient(self, abstract, concrete):
+        """
+        Registers a service with a transient lifetime.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any]
+            The abstract base type or alias to be bound.
+        concrete : Callable[..., Any]
+            The concrete implementation to associate with the abstract type.
+
+        Examples
+        --------
+        >>> container.transient(MyService, MyServiceImplementation)
+        """
+        pass
+
+    @abstractmethod
+    def scoped(self, abstract, concrete):
+        """
+        Registers a service with a scoped lifetime.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any]
+            The abstract base type or alias to be bound.
+        concrete : Callable[..., Any]
+            The concrete implementation to associate with the abstract type.
+
+        Examples
+        --------
+        >>> container.scoped(MyService, MyServiceImplementation)
+        """
+        pass
+
+    @abstractmethod
+    def singleton(self, abstract, concrete):
+        """
+        Registers a service with a singleton lifetime.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any]
+            The abstract base type or alias to be bound.
+        concrete : Callable[..., Any]
+            The concrete implementation to associate with the abstract type.
+
+        Examples
+        --------
+        >>> container.singleton(MyService, MyServiceImplementation)
+        """
+        pass
+
+    @abstractmethod
+    def instance(self, abstract, instance):
+        """
+        Registers an already instantiated object in the container.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any]
+            The abstract base type or alias to be bound.
+        instance : Any
+            The instance to be stored.
+
+        Raises
+        ------
+        OrionisContainerValueError
+            If the instance is None.
+
+        Examples
+        --------
+        >>> container.instance(MyService, my_service_instance)
+        """
+        pass
+
+    @abstractmethod
+    def bound(self, abstract_or_alias):
+        """
+        Checks if a service or alias is bound in the container.
+
+        Parameters
+        ----------
+        abstract_or_alias : Callable[..., Any]
+            The abstract type or alias to check.
+
+        Returns
+        -------
+        bool
+            True if the service is bound, False otherwise.
+
+        Examples
+        --------
+        >>> container.bound(MyService)
+        True
+        """
+        pass
+
+    @abstractmethod
+    def has(self, abstract_or_alias):
+        """
+        Alias for `bound()` method.
+
+        Parameters
+        ----------
+        abstract_or_alias : Callable[..., Any]
+            The abstract type or alias to check.
+
+        Returns
+        -------
+        bool
+            True if the service is bound, False otherwise.
+
+        Examples
+        --------
+        >>> container.has(MyService)
+        True
+        """
+        pass
+
+    @abstractmethod
+    def alias(self, alias, abstract):
+        """
+        Creates an alias for an existing abstract binding.
+
+        Parameters
+        ----------
+        alias : Callable[..., Any]
+            The alias name.
+        abstract : Callable[..., Any]
+            The existing abstract type to alias.
+
+        Raises
+        ------
+        OrionisContainerValueError
+            If the abstract type is not registered or the alias is already in use.
+
+        Examples
+        --------
+        >>> container.alias("DatabaseService", MyDatabaseService)
+        """
+        pass
+
+    @abstractmethod
+    def isAlias(self, name):
+        """
+        Checks if a given name is an alias.
+
+        Parameters
+        ----------
+        name : str
+            The name to check.
+
+        Returns
+        -------
+        bool
+            True if the name is an alias, False otherwise.
+
+        Raises
+        ------
+        OrionisContainerTypeError
+            If the name is not a string.
+
+        Examples
+        --------
+        >>> container.isAlias("DatabaseService")
+        True
+        """
+        pass
+
+    @abstractmethod
+    def getBindings(self):
+        """
+        Retrieves all registered service bindings.
+
+        Returns
+        -------
+        dict
+            A dictionary containing all instances, transient, scoped, singleton, and alias services.
+
+        Examples
+        --------
+        >>> container.getBindings()
+        """
+        pass
+
+    @abstractmethod
+    def getAlias(self, name):
+        """
+        Retrieves the abstract type associated with an alias.
+
+        Parameters
+        ----------
+        name : str
+            The alias name.
+
+        Returns
+        -------
+        Callable[..., Any]
+            The abstract type associated with the alias.
+
+        Raises
+        ------
+        OrionisContainerValueError
+            If the alias is not registered.
+
+        Examples
+        --------
+        >>> container.getAlias("DatabaseService")
+        <class 'MyDatabaseService'>
+        """
+        pass
+
+    @abstractmethod
+    def forgetScopedInstances(self):
+        """
+        Clears all scoped instances.
+
+        Examples
+        --------
+        >>> container.forgetScopedInstances()
+        """
+        pass
+
+    @abstractmethod
+    def newRequest(self):
+        """
+        Resets scoped instances to handle a new request.
+
+        Examples
+        --------
+        >>> container.newRequest()
+        """
+        pass
+
+    @abstractmethod
+    async def make(self, abstract_or_alias):
+        """
+        Resolves and instantiates a service from the container.
+
+        Parameters
+        ----------
+        abstract_or_alias : Callable[..., Any]
+            The abstract type or alias to resolve.
+
+        Returns
+        -------
+        Any
+            The instantiated service.
+
+        Raises
+        ------
+        OrionisContainerException
+            If the service is not found.
+
+        Examples
+        --------
+        >>> service = await container.make(MyService)
+        """
+        pass
+
+    @abstractmethod
+    def _resolve(self, concrete, resolving=None):
+        """
+        Resolves dependencies recursively and instantiates a class.
+
+        Parameters
+        ----------
+        concrete : Callable[..., Any]
+            The concrete implementation to instantiate.
+        resolving : Optional[Deque[Type]], optional
+            A queue to track resolving dependencies and prevent circular dependencies.
+
+        Returns
+        -------
+        Any
+            The instantiated object.
+
+        Raises
+        ------
+        OrionisContainerException
+            If circular dependencies are detected or instantiation fails.
+
+        Examples
+        --------
+        >>> instance = container._resolve(MyClass)
+        """
+        pass
+
+    @abstractmethod
+    def _resolve_dependency(self, dep_type, resolving=None):
+        """
+        Resolves a dependency by instantiating or retrieving it from the container.
+
+        Parameters
+        ----------
+        dep_type : Any
+            The dependency type to resolve.
+        resolving : Optional[Deque[Type]], optional
+            A queue to track resolving dependencies.
+
+        Returns
+        -------
+        Any
+            The resolved dependency.
+
+        Raises
+        ------
+        OrionisContainerException
+            If the dependency cannot be resolved.
+
+        Examples
+        --------
+        >>> dependency = container._resolve_dependency(MyDependency)
+        """
+        pass