aspyx 1.3.0__py3-none-any.whl → 1.4.1__py3-none-any.whl

aspyx/di/configuration/configuration.py

@@ -66,10 +66,12 @@ class ConfigurationManager:
     def get(self, path: str, type: Type[T], default : Optional[T]=None) -> T:
         """
         Retrieve a configuration value by path and type, with optional coercion.
-        Arguments:
+
+        Args:
             path (str): The path to the configuration value, e.g. "database.host".
             type (Type[T]): The expected type.
             default (Optional[T]): The default value to return if the path is not found.
+
         Returns:
             T: The configuration value coerced to the specified type, or the default value if not found.
         """
@@ -119,17 +121,17 @@ class ConfigurationSource(ABC):
 
 # decorator
 
-def value(key: str, default=None):
+def inject_value(key: str, default=None):
     """
     Decorator to inject a configuration value into a method.
 
-    Arguments:
+    Args:
         key (str): The configuration key to inject.
         default: The default value to use if the key is not found.
 
     """
     def decorator(func):
-        Decorators.add(func, value, key, default)
+        Decorators.add(func, inject_value, key, default)
 
         return func
 
@@ -139,7 +141,7 @@ def value(key: str, default=None):
 @order(9)
 class ConfigurationLifecycleCallable(LifecycleCallable):
     def __init__(self,  manager: ConfigurationManager):
-        super().__init__(value, Lifecycle.ON_INJECT)
+        super().__init__(inject_value, Lifecycle.ON_INJECT)
 
         self.manager = manager
 

aspyx/di/di.py

@@ -5,14 +5,16 @@ from __future__ import annotations
 
 import inspect
 import logging
+import importlib
+import pkgutil
+import sys
 
 from abc import abstractmethod, ABC
 from enum import Enum
 import threading
-from operator import truediv
 from typing import Type, Dict, TypeVar, Generic, Optional, cast, Callable, TypedDict
 
-from aspyx.di.util import StringBuilder
+from aspyx.util import StringBuilder
 from aspyx.reflection import Decorators, TypeDescriptor, DecoratorDescriptor
 
 T = TypeVar("T")
@@ -44,9 +46,9 @@ class DIRegistrationException(DIException):
 
 class ProviderCollisionException(DIRegistrationException):
     def __init__(self, message: str, *providers: AbstractInstanceProvider):
-         super().__init__(message)
+        super().__init__(message)
 
-         self.providers = providers
+        self.providers = providers
 
     def __str__(self):
         return f"[{self.args[0]} {self.providers[1].location()} collides with {self.providers[0].location()}"
@@ -60,33 +62,76 @@ class DIRuntimeException(DIException):
 
 class AbstractInstanceProvider(ABC, Generic[T]):
     """
-    Interface for instance providers.
+    An AbstractInstanceProvider is responsible to create instances.
     """
     @abstractmethod
     def get_module(self) -> str:
-        pass
+        """
+        return the module name of the provider
+
+        Returns:
+            str: the module name of the provider
+        """
 
     def get_host(self) -> Type[T]:
+        """
+        return the class which is responsible for creation ( e.g. the injectable class )
+
+        Returns:
+            Type[T]: the class which is responsible for creation
+        """
         return type(self)
 
     @abstractmethod
     def get_type(self) -> Type[T]:
-        pass
+        """
+        return the type of the created instance
+        
+        Returns:
+            Type[T: the type]
+        """
 
     @abstractmethod
     def is_eager(self) -> bool:
-        pass
+        """
+        return True, if the provider will eagerly construct instances
+
+        Returns:
+            bool: eager flag
+        """
 
     @abstractmethod
     def get_scope(self) -> str:
-        pass
+        """
+        return the scope name
+
+        Returns:
+            str: the scope name
+        """
+
 
     def get_dependencies(self) -> (list[Type],int):
+        """
+        return the types that i depend on ( for constructor or setter injection  ).
+        The second tuple element is the number of parameters that a construction injection will require
+
+        Returns:
+            (list[Type],int): the type array and the number of parameters
+        """
         return [],1
 
     @abstractmethod
-    def create(self, environment: Environment, *args):
-        pass
+    def create(self, environment: Environment, *args) -> T:
+        """
+        Create a new instance.
+
+        Args:
+            environment: the Environment
+            *args: the required arguments
+
+        Returns:
+            T: the instance
+        """
 
     def report(self) -> str:
         return str(self)
@@ -159,6 +204,13 @@ class SingletonScopeInstanceProvider(InstanceProvider):
     def create(self, environment: Environment, *args):
         return SingletonScope()
 
+class EnvironmentScopeInstanceProvider(InstanceProvider):
+    def __init__(self):
+        super().__init__(SingletonScopeInstanceProvider, SingletonScope, False, "request")
+
+    def create(self, environment: Environment, *args):
+        return EnvironmentScope()
+
 class RequestScopeInstanceProvider(InstanceProvider):
     def __init__(self):
         super().__init__(RequestScopeInstanceProvider, RequestScope, False, "singleton")
@@ -166,7 +218,6 @@ class RequestScopeInstanceProvider(InstanceProvider):
     def create(self, environment: Environment, *args):
         return RequestScope()
 
-
 class AmbiguousProvider(AbstractInstanceProvider):
     """
     An AmbiguousProvider covers all cases, where fetching a class would lead to an ambiguity exception.
@@ -354,7 +405,7 @@ class ClassInstanceProvider(InstanceProvider):
                 for param in method.param_types:
                     types.append(param)
 
-        return (types, self.params)
+        return types, self.params
 
     def create(self, environment: Environment, *args):
         Environment.logger.debug("%s create class %s", self, self.type.__qualname__)
@@ -441,6 +492,12 @@ class FactoryInstanceProvider(InstanceProvider):
 class Lifecycle(Enum):
     """
     This enum defines the lifecycle phases that can be processed by lifecycle processors.
+    Phases are:
+
+    - ON_INJECT
+    - ON_INIT
+    - ON_RUNNING
+    - ON_DESTROY
     """
 
     __slots__ = []
@@ -591,7 +648,7 @@ class Providers:
         Providers.check.clear()
 
     @classmethod
-    def filter(cls, environment: Environment) -> Dict[Type,AbstractInstanceProvider]:
+    def filter(cls, environment: Environment, provider_filter: Callable) -> Dict[Type,AbstractInstanceProvider]:
         cache: Dict[Type,AbstractInstanceProvider] = {}
 
         context: ConditionContext = {
@@ -610,12 +667,18 @@ class Providers:
                     if result is not None:
                         raise ProviderCollisionException(f"type {clazz.__name__} already registered", result, provider)
 
-                    else:
-                        result = provider
+                    result = provider
 
             return result
 
         def provider_applies(provider: AbstractInstanceProvider) -> bool:
+            # is it in the right module?
+
+            if not provider_filter(provider):
+                return False
+
+            # check conditionals
+
             descriptor = TypeDescriptor.for_type(provider.get_host())
             if descriptor.has_decorator(conditional):
                 conditions: list[Condition] = [*descriptor.get_decorator(conditional).args]
@@ -658,7 +721,7 @@ class Providers:
 
         # filter conditional providers and fill base classes as well
 
-        for provider_type, providers in Providers.providers.items():
+        for provider_type, _ in Providers.providers.items():
             matching_provider = filter_type(provider_type)
             if matching_provider is not None:
                 cache_provider_for_type(matching_provider, provider_type)
@@ -677,7 +740,11 @@ class Providers:
 
         # and resolve
 
-        provider_context = Providers.ResolveContext(result)
+        providers = result
+        if environment.parent is not None:
+            providers = providers | environment.parent.providers # add parent providers
+
+        provider_context = Providers.ResolveContext(providers)
         for provider in mapped.values():
             provider.resolve(provider_context)
             provider_context.next() # clear dependencies
@@ -722,6 +789,10 @@ def injectable(eager=True, scope="singleton"):
 def factory(eager=True, scope="singleton"):
     """
     Decorator that needs to be used on a class that implements the Factory interface.
+
+    Args:
+        eager (bool): If True, the corresponding object will be created eagerly when the environment is created.
+        scope (str): The scope of the factory, e.g. "singleton", "request", "environment".
     """
     def decorator(cls):
         Decorators.add(cls, factory)
@@ -736,6 +807,10 @@ def factory(eager=True, scope="singleton"):
 def create(eager=True, scope="singleton"):
     """
     Any method annotated with @create will be registered as a factory method.
+
+    Args:
+        eager (bool): If True, the corresponding object will be created eagerly when the environment is created.
+        scope (str): The scope of the factory, e.g. "singleton", "request", "environment".
     """
     def decorator(func):
         Decorators.add(func, create, eager, scope)
@@ -745,7 +820,7 @@ def create(eager=True, scope="singleton"):
 
 def on_init():
     """
-    Methods annotated with @on_init will be called when the instance is created."""
+    Methods annotated with `@on_init` will be called when the instance is created."""
     def decorator(func):
         Decorators.add(func, on_init)
         return func
@@ -754,7 +829,7 @@ def on_init():
 
 def on_running():
     """
-    Methods annotated with @on_running will be called when the container up and 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
@@ -763,7 +838,7 @@ def on_running():
 
 def on_destroy():
     """
-    Methods annotated with @on_destroy will be called when the instance is destroyed.
+    Methods annotated with `@on_destroy` will be called when the instance is destroyed.
     """
     def decorator(func):
         Decorators.add(func, on_destroy)
@@ -771,18 +846,19 @@ def on_destroy():
 
     return decorator
 
-def environment(imports: Optional[list[Type]] = None):
+def module(imports: Optional[list[Type]] = None):
     """
-    This annotation is used to mark classes that control the set of injectables that will be managed based on their location
-    relative to the module of the class. All @injectable s and @factory s that are located in the same or any sub-module will
+    This annotation is used to mark classes that control the discovery process of injectables based on their location
+    relative to the module of the class. All `@injectable`s and `@factory`s that are located in the same or any sub-module will
     be registered and managed accordingly.
-    Arguments:
-        imports (Optional[list[Type]]): Optional list of imported environment types
+
+    Args:
+        imports (Optional[list[Type]]): Optional list of imported module types
     """
     def decorator(cls):
         Providers.register(ClassInstanceProvider(cls, True))
 
-        Decorators.add(cls, environment, imports)
+        Decorators.add(cls, module, imports)
         Decorators.add(cls, injectable) # do we need that?
 
         return cls
@@ -855,11 +931,28 @@ def conditional(*conditions: Condition):
 class Environment:
     """
     Central class that manages the lifecycle of instances and their dependencies.
+
+    Usage:
+
+    ```python
+    @injectable()
+    class Foo:
+        def __init__(self):
+
+    @environment()
+    class SimpleEnvironment:
+        def __init__(self):
+            pass
+
+    environment = Environment(SimpleEnvironment)
+
+    foo = environment.get(Foo)  # will create an instance of Foo
+    ```
     """
 
     # static data
 
-    logger = logging.getLogger(__name__)  # __name__ = module name
+    logger = logging.getLogger("aspyx.di")  # __name__ = module name
 
     instance : 'Environment' = None
 
@@ -894,22 +987,35 @@ class Environment:
 
         self.features = features
         self.providers: Dict[Type, AbstractInstanceProvider] = {}
+        self.instances = []
         self.lifecycle_processors: list[LifecycleProcessor] = []
 
         if self.parent is not None:
-            self.providers |= self.parent.providers
-            self.lifecycle_processors += self.parent.lifecycle_processors
-        else: #if self.type is Boot:
+            # inherit providers from parent
+
+            for provider_type, inherited_provider in self.parent.providers.items():
+                if inherited_provider.get_scope() == "environment":
+                    # replace with own environment instance provider
+                    self.providers[provider_type] = EnvironmentInstanceProvider(self, cast(EnvironmentInstanceProvider, inherited_provider).provider)
+                else:
+                    self.providers[provider_type] = inherited_provider
+
+            # inherit processors as is unless they have an environment scope
+
+            for processor in self.parent.lifecycle_processors:
+                if self.providers[type(processor)].get_scope() != "environment":
+                    self.lifecycle_processors.append(processor)
+                else:
+                    # create and remember
+                    self.lifecycle_processors.append(self.get(type(processor)))
+        else:
             self.providers[SingletonScope] = SingletonScopeInstanceProvider()
             self.providers[RequestScope]   = RequestScopeInstanceProvider()
-
-        self.instances = []
+            self.providers[EnvironmentScope] = EnvironmentScopeInstanceProvider()
 
         Environment.instance = self
 
-        # filter conditional providers
-
-        overall_providers = Providers.filter(self)
+        prefix_list : list[str] = []
 
         loaded = set()
 
@@ -918,6 +1024,36 @@ class Environment:
 
             self.providers[type] = provider
 
+        def get_type_package(type: Type):
+            module_name = type.__module__
+            module = sys.modules[module_name]
+
+            return module.__package__
+
+        def import_package(name: str):
+            """Import a package and all its submodules recursively."""
+            package = importlib.import_module(name)
+            results = {name: package}
+
+            if hasattr(package, '__path__'):  # it's a package, not a single file
+                for finder, name, ispkg in pkgutil.walk_packages(package.__path__, prefix=package.__name__ + "."):
+                    try:
+                        loaded = sys.modules
+
+                        if loaded.get(name, None) is None:
+                            Environment.logger.debug("import module %s", name)
+
+                            submodule = importlib.import_module(name)
+                            results[name] = submodule
+                        else:
+                            # skip import
+                            results[name] = loaded[name]
+
+                    except Exception as e:
+                        Environment.logger.info("failed to import module %s due to %s", name, str(e))
+
+            return results
+
         def load_environment(env: Type):
             if env not in loaded:
                 Environment.logger.debug("load environment %s", env.__qualname__)
@@ -926,28 +1062,47 @@ class Environment:
 
                 # sanity check
 
-                decorator = TypeDescriptor.for_type(env).get_decorator(environment)
+                decorator = TypeDescriptor.for_type(env).get_decorator(module)
                 if decorator is None:
                     raise DIRegistrationException(f"{env.__name__} is not an environment class")
 
-                scan = env.__module__
-                if "." in scan:
-                    scan = scan.rsplit('.', 1)[0]
+                # package
+
+                package_name = get_type_package(env)
 
                 # recursion
 
                 for import_environment in decorator.args[0] or []:
                     load_environment(import_environment)
 
+                # import package
+
+                if package_name is not None and len(package_name) > 0: # files outside of a package return None pr ""
+                    import_package(package_name)
+
                 # filter and load providers according to their module
 
-                for type, provider in overall_providers.items():
-                    if provider.get_module().startswith(scan):
-                        add_provider(type, provider)
+                module_prefix = package_name
+                if len(module_prefix) == 0:
+                    module_prefix = env.__module__
+
+                prefix_list.append(module_prefix)
+
         # go
 
         load_environment(env)
 
+        # filter according to the prefix list
+
+        def filter_provider(provider: AbstractInstanceProvider) -> bool:
+            for prefix in prefix_list:
+                if provider.get_host().__module__.startswith(prefix):
+                    return True
+
+            return False
+
+        self.providers.update(Providers.filter(self, filter_provider))
+
         # construct eager objects for local providers
 
         for provider in set(self.providers.values()):
@@ -959,6 +1114,14 @@ class Environment:
         for instance in self.instances:
             self.execute_processors(Lifecycle.ON_RUNNING, instance)
 
+    def is_registered_type(self, type: Type) -> bool:
+        provider = self.providers.get(type, None)
+        return provider is not None and not isinstance(provider, AmbiguousProvider)
+
+    def registered_types(self,  predicate: Callable[[Type], bool]) -> list[Type]:
+        return [provider.get_type() for provider in self.providers.values()
+                if predicate(provider.get_type())]
+
     # internal
 
     def has_feature(self, feature: str) -> bool:
@@ -1048,10 +1211,11 @@ class Environment:
         """
         Create or return a cached instance for the given type.
 
-        Arguments:
+        Args:
             type (Type): The desired type
 
-        Returns: The requested instance
+        Returns:
+            T: The requested instance
         """
         provider = self.providers.get(type, None)
         if provider is None:
@@ -1297,6 +1461,19 @@ class SingletonScope(Scope):
 
         return self.value
 
+@scope("environment", register=False)
+class EnvironmentScope(SingletonScope):
+    # properties
+
+    __slots__ = [
+    ]
+
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+
+
 @scope("thread")
 class ThreadScope(Scope):
     __slots__ = [
@@ -1312,11 +1489,12 @@ class ThreadScope(Scope):
     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()
+@module()
 class Boot:
     # class
 

aspyx/di/threading/synchronized.py

@@ -20,9 +20,7 @@ def synchronized():
     return decorator
 
 @advice
-class SynchronizeAdvice():
-    __slots__ = ("locks")
-
+class SynchronizeAdvice:
     # constructor
 
     def __init__(self):
@@ -41,6 +39,11 @@ class SynchronizeAdvice():
     # around
 
     @around(methods().decorated_with(synchronized))
-    def synchronize(self, invocation: Invocation):
+    def synchronize_sync(self, invocation: Invocation):
+        with self.get_lock(invocation.args[0]):
+            return invocation.proceed()
+
+    @around(methods().decorated_with(synchronized).that_are_async())
+    async def synchronize_async(self, invocation: Invocation):
         with self.get_lock(invocation.args[0]):
-            return invocation.proceed()
+            return await invocation.proceed_async()

aspyx/exception/__init__.py

@@ -0,0 +1,10 @@
+"""
+This module provides exception handling functions.
+"""
+from .exception_manager import exception_handler, handle, ExceptionManager
+
+__all__ = [
+    "exception_handler",
+    "handle",
+    "ExceptionManager"
+]