aspyx 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

aspyx/di/di.py

@@ -62,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)
@@ -163,7 +206,7 @@ class SingletonScopeInstanceProvider(InstanceProvider):
 
 class EnvironmentScopeInstanceProvider(InstanceProvider):
     def __init__(self):
-        super().__init__(SingletonScopeInstanceProvider, SingletonScope, False, "request") # TODO?
+        super().__init__(SingletonScopeInstanceProvider, SingletonScope, False, "request")
 
     def create(self, environment: Environment, *args):
         return EnvironmentScope()
@@ -273,13 +316,32 @@ class EnvironmentInstanceProvider(AbstractInstanceProvider):
 
         self.environment = environment
         self.provider = provider
-        self.dependencies = []
+        self.dependencies : list[AbstractInstanceProvider] = []
         self.scope_instance = Scopes.get(provider.get_scope(), environment)
 
+    # public
+
+    def print_tree(self, prefix=""):
+        children = self.dependencies
+        last_index = len(children) - 1
+        print(prefix + "+- " + self.report())
+
+        for i, child in enumerate(children):
+            if i == last_index:
+                # Last child
+                child_prefix = prefix + "   "
+            else:
+                # Not last child
+                child_prefix = prefix + "|  "
+
+
+            cast(EnvironmentInstanceProvider, child).print_tree(child_prefix)
+
     # implement
 
     def resolve(self, context: Providers.ResolveContext):
         context.add(self)
+        context.push(self)
 
         if not context.is_resolved(self):
             context.provider_dependencies[self] = [] #?
@@ -289,7 +351,7 @@ class EnvironmentInstanceProvider(AbstractInstanceProvider):
             for type in type_and_params[0]:
                 if params > 0:
                     params -= 1
-                    self.dependencies.append(context.get_provider(type))
+                    self.dependencies.append(context.get_provider(type)) # try/catch TODO
 
                 provider = context.add_provider_dependency(self, type)
                 if provider is not None:
@@ -298,6 +360,8 @@ class EnvironmentInstanceProvider(AbstractInstanceProvider):
         else:
             context.add(*context.get_provider_dependencies(self))
 
+        context.pop()
+
     def get_module(self) -> str:
         return self.provider.get_module()
 
@@ -360,9 +424,13 @@ class ClassInstanceProvider(InstanceProvider):
         for method in TypeDescriptor.for_type(self.type).get_methods():
             if method.has_decorator(inject):
                 for param in method.param_types:
+                    if not Providers.is_registered(param):
+                        raise DIRegistrationException(f"{self.type.__name__}.{method.method.__name__} declares an unknown parameter type {param.__name__}")
+
                     types.append(param)
+        # done
 
-        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__)
@@ -388,28 +456,28 @@ class FunctionInstanceProvider(InstanceProvider):
 
     # constructor
 
-    def __init__(self, clazz : Type, method, return_type : Type[T], eager = True, scope = "singleton"):
-        super().__init__(clazz, return_type, eager, scope)
+    def __init__(self, clazz : Type, method: TypeDescriptor.MethodDescriptor, eager = True, scope = "singleton"):
+        super().__init__(clazz, method.return_type, eager, scope)
 
-        self.method = method
+        self.method : TypeDescriptor.MethodDescriptor = method
 
     # implement
 
     def get_dependencies(self) -> (list[Type],int):
-        return [self.host], 1
+        return [self.host, *self.method.param_types], 1 + len(self.method.param_types)
 
     def create(self, environment: Environment, *args):
         Environment.logger.debug("%s create class %s", self, self.type.__qualname__)
 
-        instance = self.method(*args) # args[0]=self
+        instance = self.method.method(*args) # args[0]=self
 
         return environment.created(instance)
 
     def report(self) -> str:
-        return f"{self.host.__name__}.{self.method.__name__}"
+        return f"{self.host.__name__}.{self.method.get_name()}({', '.join(t.__name__ for t in self.method.param_types)}) -> {self.type.__qualname__}"
 
     def __str__(self):
-        return f"FunctionInstanceProvider({self.host.__name__}.{self.method.__name__} -> {self.type.__name__})"
+        return f"FunctionInstanceProvider({self.host.__name__}.{self.method.get_name()}({', '.join(t.__name__ for t in self.method.param_types)}) -> {self.type.__name__})"
 
 class FactoryInstanceProvider(InstanceProvider):
     """
@@ -440,7 +508,7 @@ class FactoryInstanceProvider(InstanceProvider):
         return environment.created(args[0].create())
 
     def report(self) -> str:
-        return f"{self.host.__name__}.create"
+        return f"{self.host.__name__}.create() -> {self.type.__name__} "
 
     def __str__(self):
         return f"FactoryInstanceProvider({self.host.__name__} -> {self.type.__name__})"
@@ -449,6 +517,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__ = []
@@ -504,7 +578,8 @@ class Providers:
         __slots__ = [
             "dependencies",
             "providers",
-            "provider_dependencies"
+            "provider_dependencies",
+            "path"
         ]
 
         # constructor
@@ -512,6 +587,7 @@ class Providers:
         def __init__(self, providers: Dict[Type, EnvironmentInstanceProvider]):
             self.dependencies : list[EnvironmentInstanceProvider] = []
             self.providers = providers
+            self.path = []
             self.provider_dependencies : dict[EnvironmentInstanceProvider, list[EnvironmentInstanceProvider]] = {}
 
         # public
@@ -537,7 +613,14 @@ class Providers:
 
             return provider
 
+        def push(self, provider):
+            self.path.append(provider)
+
+        def pop(self):
+            self.path.pop()
+
         def next(self):
+            self.path.clear()
             self.dependencies.clear()
 
         def get_provider(self, type: Type) -> EnvironmentInstanceProvider:
@@ -558,7 +641,7 @@ class Providers:
             cycle = ""
 
             first = True
-            for p in self.dependencies:
+            for p in self.path:
                 if not first:
                     cycle += " -> "
 
@@ -589,6 +672,10 @@ class Providers:
         else:
             candidates.append(provider)
 
+    @classmethod
+    def is_registered(cls,type: Type) -> bool:
+        return Providers.providers.get(type, None) is not None
+
     # add factories lazily
 
     @classmethod
@@ -603,7 +690,7 @@ class Providers:
         cache: Dict[Type,AbstractInstanceProvider] = {}
 
         context: ConditionContext = {
-            "requires_feature": lambda feature : environment.has_feature(feature),
+            "requires_feature": environment.has_feature,
             "requires_class": lambda clazz : cache.get(clazz, None) is not None # ? only works if the class is in the cache already?
         }
 
@@ -659,10 +746,13 @@ class Providers:
                 if type is provider.get_type():
                     raise ProviderCollisionException(f"type {type.__name__} already registered", existing_provider, provider)
 
-                if isinstance(existing_provider, AmbiguousProvider):
-                    cast(AmbiguousProvider, existing_provider).add_provider(provider)
-                else:
-                    cache[type] = AmbiguousProvider(type, existing_provider, provider)
+                if existing_provider.get_type() is not type:
+                    # only overwrite if the existing provider is not specific
+
+                    if isinstance(existing_provider, AmbiguousProvider):
+                        cast(AmbiguousProvider, existing_provider).add_provider(provider)
+                    else:
+                        cache[type] = AmbiguousProvider(type, existing_provider, provider)
 
             # recursion
 
@@ -714,8 +804,7 @@ def register_factories(cls: 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]))
+            Providers.register(FunctionInstanceProvider(cls, method, create_decorator.args[0], create_decorator.args[1]))
 def order(prio = 0):
     def decorator(cls):
         Decorators.add(cls, order, prio)
@@ -740,6 +829,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)
@@ -754,6 +847,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)
@@ -763,7 +860,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
@@ -772,7 +869,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
@@ -781,7 +878,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)
@@ -789,18 +886,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
@@ -873,11 +971,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):
+
+    @module()
+    class Module:
+        def __init__(self):
+            pass
+
+    environment = Environment(Module)
+
+    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
 
@@ -951,9 +1066,33 @@ class Environment:
 
         def get_type_package(type: Type):
             module_name = type.__module__
-            module = sys.modules[module_name]
+            module = sys.modules.get(module_name)
+
+            if not module:
+                raise ImportError(f"Module {module_name} not found")
+
+            # Try to get the package
+
+            package = getattr(module, '__package__', None)
 
-            return module.__package__
+            # Fallback: if module is __main__, try to infer from the module name if possible
+
+            if not package:
+                if module_name == '__main__':
+                    # Try to resolve real name via __file__
+                    path = getattr(module, '__file__', None)
+                    if path:
+                        Environment.logger.warning(
+                            "Module is __main__; consider running via -m to preserve package context")
+                    return ''
+
+                # Try to infer package name from module name
+
+                parts = module_name.split('.')
+                if len(parts) > 1:
+                    return '.'.join(parts[:-1])
+
+            return package or ''
 
         def import_package(name: str):
             """Import a package and all its submodules recursively."""
@@ -987,7 +1126,7 @@ 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")
 
@@ -1031,6 +1170,9 @@ class Environment:
         # construct eager objects for local providers
 
         for provider in set(self.providers.values()):
+            if isinstance(provider, EnvironmentInstanceProvider):
+                provider.print_tree()
+
             if provider.is_eager():
                 provider.create(self)
 
@@ -1136,10 +1278,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:
@@ -1413,11 +1556,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/exception/__init__.py

@@ -1,5 +1,5 @@
 """
-This module provides utility functions.
+This module provides exception handling functions.
 """
 from .exception_manager import exception_handler, handle, ExceptionManager
 

aspyx/exception/exception_manager.py

@@ -32,9 +32,6 @@ def handle():
 
     return decorator
 
-class ErrorContext():
-    pass
-
 class Handler:
     # constructor
 
@@ -43,8 +40,13 @@ class Handler:
         self.instance = instance
         self.handler = handler
 
-    def handle(self, exception: BaseException):
-        self.handler(self.instance, exception)
+    def handle(self, exception: BaseException) -> BaseException:
+        result = self.handler(self.instance, exception)
+
+        if result is not None:
+            return result
+        else:
+            return exception
 
 class Chain:
     # constructor
@@ -55,11 +57,11 @@ class Chain:
 
     # public
 
-    def handle(self, exception: BaseException):
-        self.handler.handle(exception)
+    def handle(self, exception: BaseException) -> BaseException:
+        return self.handler.handle(exception)
 
 class Invocation:
-    def __init__(self, exception: Exception, chain: Chain):
+    def __init__(self, exception: BaseException, chain: Chain):
         self.exception = exception
         self.chain = chain
         self.current = self.chain
@@ -74,17 +76,26 @@ class ExceptionManager:
 
     exception_handler_classes = []
 
-    invocation = ThreadLocal()
+    invocation = ThreadLocal[Invocation]()
 
     # class methods
 
     @classmethod
-    def proceed(cls):
+    def proceed(cls) -> BaseException:
+        """
+        proceed with the next most applicable handler
+
+        Returns:
+            BaseException: the resulting exception
+
+        """
         invocation = cls.invocation.get()
 
         invocation.current = invocation.current.next
         if invocation.current is not None:
-            invocation.current.handle(invocation.exception)
+            return invocation.current.handle(invocation.exception)
+        else:
+            return invocation.exception
 
     # constructor
 
@@ -93,7 +104,6 @@ class ExceptionManager:
         self.handler : list[Handler] = []
         self.cache: Dict[Type, Chain] = {}
         self.lock = RLock()
-        self.current_context: Optional[ErrorContext] = None
 
     # internal
 
@@ -145,7 +155,7 @@ class ExceptionManager:
 
         # chain
 
-        for i in range(0, len(chain) - 2):
+        for i in range(0, len(chain) - 1):
             chain[i].next = chain[i + 1]
 
         if len(chain) > 0:
@@ -153,16 +163,23 @@ class ExceptionManager:
         else:
             return None
 
-    def handle(self, exception: Exception):
+    def handle(self, exception: BaseException) -> BaseException:
         """
-        handle an exception by invoking the most applicable handler ( according to mro )
-        :param exception: the exception
+        handle an exception by invoking the most applicable handler (according to mro)
+        and return a possible modified exception as a result.
+
+        Args:
+            exception (BaseException): the exception
+
+        Returns:
+            BaseException: the resulting exception
         """
         chain = self.get_handlers(type(exception))
         if chain is not None:
-
             self.invocation.set(Invocation(exception, chain))
             try:
-                chain.handle(exception)
+                return chain.handle(exception)
             finally:
                 self.invocation.clear()
+        else:
+            return exception # hmmm?

aspyx/reflection/proxy.py

@@ -1,7 +1,8 @@
 """
 Dynamic proxies for method interception and delegation.
 """
-from typing import Generic, TypeVar, Type
+import inspect
+from typing import Generic, TypeVar, Type, Callable
 
 T = TypeVar("T")
 
@@ -14,6 +15,7 @@ class DynamicProxy(Generic[T]):
     by intercepting method calls at runtime and handling them as needed.
 
     Usage:
+    ```python
         class MyHandler(DynamicProxy.InvocationHandler):
             def invoke(self, invocation):
                 print(f"Intercepted: {invocation.name}")
@@ -22,17 +24,23 @@ class DynamicProxy(Generic[T]):
 
         proxy = DynamicProxy.create(SomeClass, MyHandler())
         proxy.some_method(args)  # Will be intercepted by MyHandler.invoke
-
-    Attributes:
-        type: The proxied class type.
-        invocation_handler: The handler that processes intercepted method calls.
+    ```
     """
     # inner class
 
     class Invocation:
-        def __init__(self, type: Type[T], name: str, *args, **kwargs):
+        __slots__ = [
+            "type",
+            "method",
+            "args",
+            "kwargs",
+        ]
+
+        # constructor
+
+        def __init__(self, type: Type[T], method: Callable, *args, **kwargs):
             self.type = type
-            self.name = name
+            self.method = method
             self.args = args
             self.kwargs = kwargs
 
@@ -40,12 +48,20 @@ class DynamicProxy(Generic[T]):
         def invoke(self, invocation: 'DynamicProxy.Invocation'):
             pass
 
+        async def invoke_async(self, invocation: 'DynamicProxy.Invocation'):
+            return self.invoke(invocation)
+
     # class methods
 
     @classmethod
     def create(cls, type: Type[T], invocation_handler: 'DynamicProxy.InvocationHandler') -> T:
         return DynamicProxy(type, invocation_handler)
 
+    __slots__ = [
+        "type",
+        "invocation_handler"
+    ]
+
     # constructor
 
     def __init__(self, type: Type[T], invocation_handler: 'DynamicProxy.InvocationHandler'):
@@ -55,7 +71,16 @@ class DynamicProxy(Generic[T]):
     # public
 
     def __getattr__(self, name):
-        def wrapper(*args, **kwargs):
-            return self.invocation_handler.invoke(DynamicProxy.Invocation(self.type, name, *args, **kwargs))
+        method = getattr(self.type, name)
+
+        if  inspect.iscoroutinefunction(method):
+            async def async_wrapper(*args, **kwargs):
+                return  await self.invocation_handler.invoke_async(DynamicProxy.Invocation(self.type, method, *args, **kwargs))
+
+            return async_wrapper
+
+        else:
+            def sync_wrapper(*args, **kwargs):
+                return self.invocation_handler.invoke(DynamicProxy.Invocation(self.type, method, *args, **kwargs))
 
-        return wrapper
+            return sync_wrapper