aspyx 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

aspyx/di/di.py

@@ -1,5 +1,5 @@
 """
-The deoendency injection module provides a framework for managing dependencies and lifecycle of objects in Python applications.
+The dependency injection module provides a framework for managing dependencies and lifecycle of objects in Python applications.
 """
 from __future__ import annotations
 
@@ -7,10 +7,11 @@ import inspect
 import logging
 
 from abc import abstractmethod, ABC
-from enum import Enum, auto
+from enum import Enum
 import threading
 from typing import Type, Dict, TypeVar, Generic, Optional, cast, Callable
 
+from aspyx.di.util import StringBuilder
 from aspyx.reflection import Decorators, TypeDescriptor, DecoratorDescriptor
 
 T = TypeVar("T")
@@ -26,11 +27,21 @@ class Factory(ABC, Generic[T]):
     def create(self) -> T:
         pass
 
-class InjectorException(Exception):
+class DIException(Exception):
     """
     Exception raised for errors in the injector.
     """
 
+class DIRegistrationException(DIException):
+    """
+    Exception raised during the registration of dependencies.
+    """
+
+class DIRuntimeException(DIException):
+    """
+    Exception raised during the runtime.
+    """
+
 class AbstractInstanceProvider(ABC, Generic[T]):
     """
     Interface for instance providers.
@@ -39,6 +50,9 @@ class AbstractInstanceProvider(ABC, Generic[T]):
     def get_module(self) -> str:
         pass
 
+    def get_host(self) -> Type[T]:
+        return type(self)
+
     @abstractmethod
     def get_type(self) -> Type[T]:
         pass
@@ -60,7 +74,10 @@ class AbstractInstanceProvider(ABC, Generic[T]):
         pass
 
     @abstractmethod
-    def resolve(self, context: Providers.Context) -> AbstractInstanceProvider:
+    def resolve(self, context: Providers.Context):
+        pass
+
+    def check_factories(self):
         pass
 
 
@@ -85,10 +102,22 @@ class InstanceProvider(AbstractInstanceProvider):
         self.scope = scope
         self.dependencies : Optional[list[AbstractInstanceProvider]] = None
 
+    # internal
+
+    def _is_resolved(self) -> bool:
+        return self.dependencies is not None
+
     # implement AbstractInstanceProvider
 
-    def resolve(self, context: Providers.Context) -> AbstractInstanceProvider:
-        return self
+    def get_host(self):
+        return self.host
+
+    def check_factories(self):
+        #register_factories(self.host)
+        pass
+
+    def resolve(self, context: Providers.Context):
+        pass
 
     def get_module(self) -> str:
         return self.host.__module__
@@ -178,11 +207,11 @@ class AmbiguousProvider(AbstractInstanceProvider):
     def get_dependencies(self) -> list[AbstractInstanceProvider]:
         return []
 
-    def resolve(self, context: Providers.Context) -> AbstractInstanceProvider:
-        return self
+    def resolve(self, context: Providers.Context):
+        pass
 
     def create(self, environment: Environment, *args):
-        raise InjectorException(f"multiple candidates for type {self.type}")
+        raise DIException(f"multiple candidates for type {self.type}")
 
     def __str__(self):
         return f"AmbiguousProvider({self.type})"
@@ -198,7 +227,7 @@ class Scopes:
     def get(cls, scope: str, environment: Environment):
         scope_type = Scopes.scopes.get(scope, None)
         if scope_type is None:
-            raise InjectorException(f"unknown scope type {scope}")
+            raise DIRegistrationException(f"unknown scope type {scope}")
 
         return environment.get(scope_type)
 
@@ -245,7 +274,7 @@ class EnvironmentInstanceProvider(AbstractInstanceProvider):
 
     # implement
 
-    def resolve(self, context: Providers.Context) -> AbstractInstanceProvider:
+    def resolve(self, context: Providers.Context):
         pass # noop
 
     def get_module(self) -> str:
@@ -266,7 +295,7 @@ class EnvironmentInstanceProvider(AbstractInstanceProvider):
         for dependency in self.provider.get_dependencies():
             instance_provider = providers.get(dependency.get_type(), None)
             if instance_provider is None:
-                raise InjectorException(f"missing import for {dependency.get_type()} ")
+                raise DIRegistrationException(f"missing import for {dependency.get_type()} ")
 
             self.dependencies.append(instance_provider)
 
@@ -297,22 +326,25 @@ class ClassInstanceProvider(InstanceProvider):
 
     # implement
 
-    def resolve(self, context: Providers.Context) -> InstanceProvider:
-        if self.dependencies is None:
-            self.dependencies = []
+    def check_factories(self):
+        register_factories(self.host)
+
+    def resolve(self, context: Providers.Context):
+        context.add(self)
 
-            context.add(self)
+        if not self._is_resolved():
+            self.dependencies = []
 
             # check constructor
 
             init = TypeDescriptor.for_type(self.type).get_method("__init__")
             if init is None:
-                raise InjectorException(f"{self.type.__name__} does not implement __init__")
+                raise DIRegistrationException(f"{self.type.__name__} does not implement __init__")
 
             for param in init.param_types:
                 provider = Providers.get_provider(param)
                 self.params += 1
-                if self.add_dependency(provider):
+                if self.add_dependency(provider): # a dependency can occur multiple times, e.g in __init__ and in an injected method
                     provider.resolve(context)
 
             # check @inject
@@ -327,8 +359,6 @@ class ClassInstanceProvider(InstanceProvider):
         else: # check if the dependencies create a cycle
             context.add(*self.dependencies)
 
-        return self
-
     def create(self, environment: Environment, *args):
         Environment.logger.debug("%s create class %s", self, self.type.__qualname__)
 
@@ -357,11 +387,11 @@ class FunctionInstanceProvider(InstanceProvider):
 
     # implement
 
-    def resolve(self, context: Providers.Context) -> AbstractInstanceProvider:
-        if self.dependencies is None:
-            self.dependencies = []
+    def resolve(self, context: Providers.Context):
+        context.add(self)
 
-            context.add(self)
+        if not self._is_resolved():
+            self.dependencies = []
 
             provider = Providers.get_provider(self.host)
             if self.add_dependency(provider):
@@ -369,8 +399,6 @@ class FunctionInstanceProvider(InstanceProvider):
         else: # check if the dependencies crate a cycle
             context.add(*self.dependencies)
 
-        return self
-
     def create(self, environment: Environment, *args):
         Environment.logger.debug("%s create class %s", self, self.type.__qualname__)
 
@@ -401,16 +429,15 @@ class FactoryInstanceProvider(InstanceProvider):
 
     # implement
 
-    def resolve(self, context: Providers.Context) -> AbstractInstanceProvider:
-        if self.dependencies is None:
-            self.dependencies = []
+    def resolve(self, context: Providers.Context):
+        context.add(self)
 
-            context.add(self)
+        if  not self._is_resolved():
+            self.dependencies = []
 
             provider = Providers.get_provider(self.host)
             if self.add_dependency(provider):
                 provider.resolve(context)
-
         else: # check if the dependencies crate a cycle
             context.add(*self.dependencies)
 
@@ -432,8 +459,10 @@ class Lifecycle(Enum):
 
     __slots__ = []
 
-    ON_INIT = auto()
-    ON_DESTROY = auto()
+    ON_INJECT  = 0
+    ON_INIT    = 1
+    ON_RUNNING = 2
+    ON_DESTROY = 3
 
 class LifecycleProcessor(ABC):
     """
@@ -486,7 +515,7 @@ class Providers:
         def add(self, *providers: AbstractInstanceProvider):
             for provider in providers:
                 if next((p for p in self.dependencies if p.get_type() is provider.get_type()), None) is not None:
-                    raise InjectorException(self.cycle_report(provider))
+                    raise DIRegistrationException(self.cycle_report(provider))
 
                 self.dependencies.append(provider)
 
@@ -502,7 +531,7 @@ class Providers:
 
                 cycle += f"{p.get_type().__name__}"
 
-            cycle += f" -> {provider.get_type().__name__}"
+            cycle += f" <> {provider.get_type().__name__}"
 
             return cycle
 
@@ -538,13 +567,20 @@ class Providers:
             return True
 
         def cache_provider_for_type(provider: AbstractInstanceProvider, type: Type):
+            def location(provider: AbstractInstanceProvider):
+                host = provider.get_host()
+                file = inspect.getfile(host)
+                line = inspect.getsourcelines(host)[1]
+
+                return f"{file}:{line}"
+
             existing_provider = Providers.cache.get(type)
             if existing_provider is None:
                 Providers.cache[type] = provider
 
             else:
                 if type is provider.get_type():
-                    raise InjectorException(f"{type} already registered")
+                    raise DIRegistrationException(f"{type} already registered in {location(existing_provider)}, override in {location(provider)}")
 
                 if isinstance(existing_provider, AmbiguousProvider):
                     cast(AmbiguousProvider, existing_provider).add_provider(provider)
@@ -569,12 +605,14 @@ class Providers:
 
     @classmethod
     def resolve(cls):
-        for provider in Providers.check:
-            provider.resolve(Providers.Context())
 
-        Providers.check.clear()
+        for check in  Providers.check:
+            check.check_factories()
 
-        #Providers.report()
+        # in the loop additional providers may be added
+        while len(Providers.check) > 0:
+            check = Providers.check.pop(0)
+            check.resolve(Providers.Context())
 
     @classmethod
     def report(cls):
@@ -585,7 +623,7 @@ class Providers:
     def get_provider(cls, type: Type) -> AbstractInstanceProvider:
         provider = Providers.cache.get(type, None)
         if provider is None:
-            raise InjectorException(f"{type.__name__} not registered as injectable")
+            raise DIException(f"{type.__name__} not registered as injectable")
 
         return provider
 
@@ -595,7 +633,11 @@ def register_factories(cls: Type):
     for method in descriptor.get_methods():
         if method.has_decorator(create):
             create_decorator = method.get_decorator(create)
-            Providers.register(FunctionInstanceProvider(cls, method.method, method.return_type, create_decorator.args[0],
+            return_type = method.return_type
+            if return_type is None:
+                raise DIRegistrationException(f"{cls.__name__}.{method.method.__name__} expected to have a return type")
+
+            Providers.register(FunctionInstanceProvider(cls, method.method, return_type, create_decorator.args[0],
                                                         create_decorator.args[1]))
 def order(prio = 0):
     def decorator(cls):
@@ -614,8 +656,6 @@ def injectable(eager=True, scope="singleton"):
 
         Providers.register(ClassInstanceProvider(cls, eager, scope))
 
-        #TODO registerFactories(cls)
-
         return cls
 
     return decorator
@@ -653,6 +693,15 @@ def on_init():
 
     return decorator
 
+def on_running():
+    """
+    Methods annotated with @on_running will be called when the container up and running."""
+    def decorator(func):
+        Decorators.add(func, on_running)
+        return func
+
+    return decorator
+
 def on_destroy():
     """
     Methods annotated with @on_destroy will be called when the instance is destroyed.
@@ -677,8 +726,6 @@ def environment(imports: Optional[list[Type]] = None):
         Decorators.add(cls, environment, imports)
         Decorators.add(cls, injectable) # do we need that?
 
-        register_factories(cls)
-
         return cls
 
     return decorator
@@ -736,8 +783,8 @@ class Environment:
 
         self.type = env
         self.parent = parent
-        if self.parent is None and env is not BootEnvironment:
-            self.parent = BootEnvironment.get_instance() # inherit environment including its manged instances!
+        if self.parent is None and env is not Boot:
+            self.parent = Boot.get_environment() # inherit environment including its manged instances!
 
         self.providers: Dict[Type, AbstractInstanceProvider] = {}
         self.lifecycle_processors: list[LifecycleProcessor] = []
@@ -750,7 +797,7 @@ class Environment:
 
         Environment.instance = self
 
-        # resolve providers on a static basis. This is only executed once!
+        # resolve providers on a static basis. This is executed for all new providers ( in case of new modules multiple times) !
 
         Providers.resolve()
 
@@ -763,7 +810,7 @@ class Environment:
 
         # bootstrapping hack, they will be overwritten by the "real" providers
 
-        if env is BootEnvironment:
+        if env is Boot:
             add_provider(SingletonScope, SingletonScopeInstanceProvider())
             add_provider(RequestScope, RequestScopeInstanceProvider())
 
@@ -777,7 +824,7 @@ class Environment:
 
                 decorator = TypeDescriptor.for_type(env).get_decorator(environment)
                 if decorator is None:
-                    raise InjectorException(f"{env.__name__} is not an environment class")
+                    raise DIRegistrationException(f"{env.__name__} is not an environment class")
 
                 scan = env.__module__
                 if "." in scan:
@@ -794,7 +841,7 @@ class Environment:
 
                 # register providers
 
-                # make sure, that for every type ony a single EnvironmentInstanceProvider is created!
+                # make sure, that for every type only a single EnvironmentInstanceProvider is created!
                 # otherwise inheritance will fuck it up
 
                 environment_providers : dict[AbstractInstanceProvider, EnvironmentInstanceProvider] = {}
@@ -823,6 +870,12 @@ class Environment:
         for provider in load_environment(env):
             if provider.is_eager():
                 provider.create(self)
+
+        # running callback
+
+        for instance in self.instances:
+            self.execute_processors(Lifecycle.ON_RUNNING, instance)
+
     # internal
 
     def execute_processors(self, lifecycle: Lifecycle, instance: T) -> T:
@@ -847,10 +900,54 @@ class Environment:
 
         # execute processors
 
-        return self.execute_processors(Lifecycle.ON_INIT, instance)
+        self.execute_processors(Lifecycle.ON_INJECT, instance)
+        self.execute_processors(Lifecycle.ON_INIT, instance)
+
+        return instance
 
     # public
 
+    def report(self):
+        builder = StringBuilder()
+
+        builder.append(f"Environment {self.type.__name__}")
+
+        if self.parent is not None:
+            builder.append(f" parent {self.parent.type.__name__}")
+
+        builder.append("\n")
+
+        # post processors
+
+        builder.append("Processors \n")
+        for processor in self.lifecycle_processors:
+            builder.append(f"- {processor.__class__.__name__}\n")
+
+        # providers
+
+        builder.append("Providers \n")
+        for result_type, provider in self.providers.items():
+            if cast(EnvironmentInstanceProvider, provider).environment is self:
+                builder.append(f"- {result_type.__name__}: {cast(EnvironmentInstanceProvider, provider).provider}\n")
+
+        # instances
+
+        builder.append("Instances \n")
+
+        result = {}
+        for obj in self.instances:
+            cls = type(obj)
+            result[cls] = result.get(cls, 0) + 1
+
+        for cls, count in result.items():
+            builder.append(f"- {cls.__name__}: {count} \n")
+
+        # done
+
+        result = str(builder)
+
+        return result
+
     def destroy(self):
         """
         destroy all managed instances by calling the appropriate lifecycle methods
@@ -862,7 +959,7 @@ class Environment:
 
     def get(self, type: Type[T]) -> T:
         """
-        Return and possibly create a new instance of the given type.
+        Create or return a cached instance for the given type.
 
         Arguments:
             type (Type): The desired type
@@ -872,7 +969,7 @@ class Environment:
         provider = self.providers.get(type, None)
         if provider is None:
             Environment.logger.error("%s is not supported", type)
-            raise InjectorException(f"{type} is not supported")
+            raise DIRuntimeException(f"{type} is not supported")
 
         return provider.create(self)
 
@@ -883,22 +980,21 @@ class LifecycleCallable:
         "order"
     ]
 
-    def __init__(self, decorator, processor: CallableProcessor, lifecycle: Lifecycle):
+    def __init__(self, decorator, lifecycle: Lifecycle):
         self.decorator = decorator
         self.lifecycle = lifecycle
         self.order = 0
 
         if TypeDescriptor.for_type(type(self)).has_decorator(order):
-            self.order =  TypeDescriptor.for_type(type(self)).get_decorator(order).args[0]
+            self.order = TypeDescriptor.for_type(type(self)).get_decorator(order).args[0]
 
-        processor.register(self)
+        AbstractCallableProcessor.register(self)
 
     def args(self, decorator: DecoratorDescriptor, method: TypeDescriptor.MethodDescriptor, environment: Environment):
         return []
 
-@injectable()
-@order(1)
-class CallableProcessor(LifecycleProcessor):
+
+class AbstractCallableProcessor(LifecycleProcessor):
     # local classes
 
     class MethodCall:
@@ -921,74 +1017,127 @@ class CallableProcessor(LifecycleProcessor):
         def __str__(self):
             return f"MethodCall({self.method.method.__name__})"
 
-    # constructor
+    # static data
 
-    def __init__(self):
-        super().__init__()
+    lock = threading.RLock()
+    callables : Dict[object, LifecycleCallable] = {}
+    cache : Dict[Type, list[list[AbstractCallableProcessor.MethodCall]]] = {}
+
+    # static methods
 
-        self.callables : Dict[object,LifecycleCallable] = {}
-        self.cache : Dict[Type,list[CallableProcessor.MethodCall]]  = {}
+    @classmethod
+    def register(cls, callable: LifecycleCallable):
+        AbstractCallableProcessor.callables[callable.decorator] = callable
 
-    def compute_callables(self, type: Type) -> list[CallableProcessor.MethodCall] :
+    @classmethod
+    def compute_callables(cls, type: Type) -> list[list[AbstractCallableProcessor.MethodCall]]:
         descriptor = TypeDescriptor.for_type(type)
 
-        result = []
+        result = [[], [], [], []]  # per lifecycle
 
         for method in descriptor.get_methods():
             for decorator in method.decorators:
-                if self.callables.get(decorator.decorator) is not None:
-                    result.append(CallableProcessor.MethodCall(method, decorator, self.callables[decorator.decorator]))
+                callable = AbstractCallableProcessor.callables.get(decorator.decorator)
+                if callable is not None:  # any callable for this decorator?
+                    result[callable.lifecycle.value].append(
+                        AbstractCallableProcessor.MethodCall(method, decorator, callable))
 
         # sort according to order
 
-        result.sort(key=lambda call: call.lifecycle_callable.order)
+        result[0].sort(key=lambda call: call.lifecycle_callable.order)
+        result[1].sort(key=lambda call: call.lifecycle_callable.order)
+        result[2].sort(key=lambda call: call.lifecycle_callable.order)
+        result[3].sort(key=lambda call: call.lifecycle_callable.order)
 
         # done
 
         return result
 
-    def callables_for(self, type: Type)-> list[CallableProcessor.MethodCall]:
-        callables = self.cache.get(type, None)
+    @classmethod
+    def callables_for(cls, type: Type) -> list[list[AbstractCallableProcessor.MethodCall]]:
+        callables = AbstractCallableProcessor.cache.get(type, None)
         if callables is None:
-            callables = self.compute_callables(type)
-            self.cache[type] = callables
+            with AbstractCallableProcessor.lock:
+                callables = AbstractCallableProcessor.cache.get(type, None)
+                if callables is None:
+                    callables = AbstractCallableProcessor.compute_callables(type)
+                    AbstractCallableProcessor.cache[type] = callables
 
         return callables
 
-    def register(self, callable: LifecycleCallable):
-        self.callables[callable.decorator] = callable
+    # constructor
+
+    def __init__(self, lifecycle: Lifecycle):
+        super().__init__()
+
+        self.lifecycle = lifecycle
 
     # implement
 
     def process_lifecycle(self, lifecycle: Lifecycle, instance: object, environment: Environment) -> object:
-        callables = self.callables_for(type(instance))
-        for callable in callables:
-            if callable.lifecycle_callable.lifecycle is lifecycle:
+        if lifecycle is self.lifecycle:
+            callables = self.callables_for(type(instance))
+
+            for callable in callables[lifecycle.value]:
                 callable.execute(instance, environment)
 
+@injectable()
+@order(1)
+class OnInjectCallableProcessor(AbstractCallableProcessor):
+    def __init__(self):
+        super().__init__(Lifecycle.ON_INJECT)
+
+@injectable()
+@order(2)
+class OnInitCallableProcessor(AbstractCallableProcessor):
+    def __init__(self):
+        super().__init__(Lifecycle.ON_INIT)
+
+@injectable()
+@order(3)
+class OnRunningCallableProcessor(AbstractCallableProcessor):
+    def __init__(self):
+        super().__init__(Lifecycle.ON_RUNNING)
+
+@injectable()
+@order(4)
+class OnDestroyCallableProcessor(AbstractCallableProcessor):
+    def __init__(self):
+        super().__init__(Lifecycle.ON_DESTROY)
+
+# the callables
+
 @injectable()
 @order(1000)
 class OnInitLifecycleCallable(LifecycleCallable):
     __slots__ = []
 
-    def __init__(self, processor: CallableProcessor):
-        super().__init__(on_init, processor, Lifecycle.ON_INIT)
+    def __init__(self):
+        super().__init__(on_init, Lifecycle.ON_INIT)
 
 @injectable()
 @order(1001)
 class OnDestroyLifecycleCallable(LifecycleCallable):
     __slots__ = []
 
-    def __init__(self, processor: CallableProcessor):
-        super().__init__(on_destroy, processor, Lifecycle.ON_DESTROY)
+    def __init__(self):
+        super().__init__(on_destroy, Lifecycle.ON_DESTROY)
+
+@injectable()
+@order(1002)
+class OnRunningLifecycleCallable(LifecycleCallable):
+    __slots__ = []
+
+    def __init__(self):
+        super().__init__(on_running, Lifecycle.ON_RUNNING)
 
 @injectable()
 @order(9)
 class EnvironmentAwareLifecycleCallable(LifecycleCallable):
     __slots__ = []
 
-    def __init__(self, processor: CallableProcessor):
-        super().__init__(inject_environment, processor, Lifecycle.ON_INIT)
+    def __init__(self):
+        super().__init__(inject_environment, Lifecycle.ON_INJECT)
 
     def args(self, decorator: DecoratorDescriptor, method: TypeDescriptor.MethodDescriptor, environment: Environment):
         return [environment]
@@ -998,8 +1147,8 @@ class EnvironmentAwareLifecycleCallable(LifecycleCallable):
 class InjectLifecycleCallable(LifecycleCallable):
     __slots__ = []
 
-    def __init__(self, processor: CallableProcessor):
-        super().__init__(inject, processor, Lifecycle.ON_INIT)
+    def __init__(self):
+        super().__init__(inject, Lifecycle.ON_INJECT)
 
     # override
 
@@ -1046,7 +1195,7 @@ class SingletonScope(Scope):
         super().__init__()
 
         self.value = None
-        self.lock = threading.Lock()
+        self.lock = threading.RLock()
 
     # override
 
@@ -1058,20 +1207,37 @@ class SingletonScope(Scope):
 
         return self.value
 
+@scope("thread")
+class ThreadScope(Scope):
+    __slots__ = [
+        "_local"
+    ]
+
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+        self._local = threading.local()
+
+    def get(self, provider: AbstractInstanceProvider, environment: Environment, arg_provider: Callable[[], list]):
+        if not hasattr(self._local, "value"):
+            self._local.value = provider.create(environment, *arg_provider())
+        return self._local.value
+
 # internal class that is required to import technical instance providers
 
 @environment()
-class BootEnvironment:
+class Boot:
     # class
 
     environment = None
 
     @classmethod
-    def get_instance(cls):
-        if BootEnvironment.environment is None:
-            BootEnvironment.environment = Environment(BootEnvironment)
+    def get_environment(cls):
+        if Boot.environment is None:
+            Boot.environment = Environment(Boot)
 
-        return BootEnvironment.environment
+        return Boot.environment
 
     # properties