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

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()}"
@@ -159,6 +161,13 @@ class SingletonScopeInstanceProvider(InstanceProvider):
     def create(self, environment: Environment, *args):
         return SingletonScope()
 
+class EnvironmentScopeInstanceProvider(InstanceProvider):
+    def __init__(self):
+        super().__init__(SingletonScopeInstanceProvider, SingletonScope, False, "request") # TODO?
+
+    def create(self, environment: Environment, *args):
+        return EnvironmentScope()
+
 class RequestScopeInstanceProvider(InstanceProvider):
     def __init__(self):
         super().__init__(RequestScopeInstanceProvider, RequestScope, False, "singleton")
@@ -166,7 +175,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.
@@ -591,7 +599,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 +618,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 +672,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 +691,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
@@ -894,22 +912,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 +949,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__)
@@ -930,24 +991,43 @@ class Environment:
                 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 +1039,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:
@@ -1297,6 +1385,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__ = [

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 utility functions.
+"""
+from .exception_manager import exception_handler, handle, ExceptionManager
+
+__all__ = [
+    "exception_handler",
+    "handle",
+    "ExceptionManager"
+]

aspyx/exception/exception_manager.py

@@ -0,0 +1,168 @@
+"""
+Exception handling code
+"""
+from threading import RLock
+from typing import Any, Callable, Dict, Optional, Type
+
+from aspyx.di import injectable, Environment, inject_environment, on_running
+from aspyx.reflection import Decorators, TypeDescriptor
+from aspyx.threading import ThreadLocal
+
+
+def exception_handler():
+    """
+    This annotation is used to mark classes that container handlers for exceptions
+    """
+    def decorator(cls):
+        Decorators.add(cls, exception_handler)
+
+        ExceptionManager.exception_handler_classes.append(cls)
+
+        return cls
+
+    return decorator
+
+def handle():
+    """
+    Any method annotated with @handle will be registered as an exception handler method.
+    """
+    def decorator(func):
+        Decorators.add(func, handle)
+        return func
+
+    return decorator
+
+class ErrorContext():
+    pass
+
+class Handler:
+    # constructor
+
+    def __init__(self, type_: Type, instance: Any, handler: Callable):
+        self.type = type_
+        self.instance = instance
+        self.handler = handler
+
+    def handle(self, exception: BaseException):
+        self.handler(self.instance, exception)
+
+class Chain:
+    # constructor
+
+    def __init__(self, handler: Handler, next: Optional[Handler] = None):
+        self.handler = handler
+        self.next = next
+
+    # public
+
+    def handle(self, exception: BaseException):
+        self.handler.handle(exception)
+
+class Invocation:
+    def __init__(self, exception: Exception, chain: Chain):
+        self.exception = exception
+        self.chain = chain
+        self.current = self.chain
+
+@injectable()
+class ExceptionManager:
+    """
+    An exception manager collects all registered handlers and is able to handle an exception
+    by dispatching it to the most applicable handler ( according to mro )
+    """
+    # static data
+
+    exception_handler_classes = []
+
+    invocation = ThreadLocal()
+
+    # class methods
+
+    @classmethod
+    def proceed(cls):
+        invocation = cls.invocation.get()
+
+        invocation.current = invocation.current.next
+        if invocation.current is not None:
+            invocation.current.handle(invocation.exception)
+
+    # constructor
+
+    def __init__(self):
+        self.environment : Optional[Environment] = None
+        self.handler : list[Handler] = []
+        self.cache: Dict[Type, Chain] = {}
+        self.lock = RLock()
+        self.current_context: Optional[ErrorContext] = None
+
+    # internal
+
+    @inject_environment()
+    def set_environment(self, environment: Environment):
+        self.environment = environment
+
+    @on_running()
+    def setup(self):
+        for handler_class in self.exception_handler_classes:
+            type_descriptor = TypeDescriptor.for_type(handler_class)
+            instance = self.environment.get(handler_class)
+
+            # analyze methods
+
+            for method in type_descriptor.get_methods():
+                if method.has_decorator(handle):
+                    if len(method.param_types) == 1:
+                        exception_type = method.param_types[0]
+
+                        self.handler.append(Handler(
+                            exception_type,
+                            instance,
+                            method.method,
+                        ))
+                    else:
+                        print(f"handler {method.method} expected to have one parameter")
+
+    def get_handlers(self, clazz: Type) -> Optional[Chain]:
+        chain = self.cache.get(clazz, None)
+        if chain is None:
+            with self.lock:
+                chain = self.cache.get(clazz, None)
+                if chain is None:
+                    chain = self.compute_handlers(clazz)
+                    self.cache[clazz] = chain
+
+        return chain
+
+    def compute_handlers(self, clazz: Type) -> Optional[Chain]:
+        mro = clazz.mro()
+
+        chain = []
+
+        for type in mro:
+            handler = next((handler for handler in self.handler if handler.type is type), None)
+            if handler:
+                chain.append(Chain(handler))
+
+        # chain
+
+        for i in range(0, len(chain) - 2):
+            chain[i].next = chain[i + 1]
+
+        if len(chain) > 0:
+            return chain[0]
+        else:
+            return None
+
+    def handle(self, exception: Exception):
+        """
+        handle an exception by invoking the most applicable handler ( according to mro )
+        :param exception: the exception
+        """
+        chain = self.get_handlers(type(exception))
+        if chain is not None:
+
+            self.invocation.set(Invocation(exception, chain))
+            try:
+                chain.handle(exception)
+            finally:
+                self.invocation.clear()

aspyx/reflection/reflection.py

@@ -12,6 +12,9 @@ from weakref import WeakKeyDictionary
 
 
 class DecoratorDescriptor:
+    """
+    A DecoratorDescriptor covers the decorator - a callable - and the passed arguments
+    """
     __slots__ = [
         "decorator",
         "args"
@@ -29,13 +32,17 @@ class Decorators:
     Utility class that caches decorators ( Python does not have a feature for this )
     """
     @classmethod
-    def add(cls, func, decorator, *args):
+    def add(cls, func, decorator: Callable, *args):
         decorators = getattr(func, '__decorators__', None)
         if decorators is None:
             setattr(func, '__decorators__', [DecoratorDescriptor(decorator, *args)])
         else:
             decorators.append(DecoratorDescriptor(decorator, *args))
 
+    @classmethod
+    def has_decorator(cls, func, callable: Callable) -> bool:
+        return any(decorator.decorator is callable for decorator in Decorators.get(func))
+
     @classmethod
     def get(cls, func) -> list[DecoratorDescriptor]:
         return getattr(func, '__decorators__', [])
@@ -69,10 +76,34 @@ class TypeDescriptor:
 
         # public
 
+        def get_name(self) -> str:
+            """
+            return the method name
+            :return: the method name
+            """
+            return self.method.__name__
+
+        def get_doc(self, default = "") -> str:
+            """
+            return the method docstring
+            :param default: the default if no docstring is found
+            :return:  the docstring
+            """
+            return self.method.__doc__ or default
+
         def is_async(self) -> bool:
+            """
+            return true if the method is asynchronous
+            :return: async flag
+            """
             return inspect.iscoroutinefunction(self.method)
 
         def get_decorator(self, decorator: Callable) -> Optional[DecoratorDescriptor]:
+            """
+            return the DecoratorDescriptor - if any - associated with the passed Callable
+            :param decorator:
+            :return:  the DecoratorDescriptor or None
+            """
             for dec in self.decorators:
                 if dec.decorator is decorator:
                     return dec
@@ -80,6 +111,11 @@ class TypeDescriptor:
             return None
 
         def has_decorator(self, decorator: Callable) -> bool:
+            """
+            return True if the method is decorated with the decorator
+            :param decorator: the decorator callable
+            :return:  True if the method is decorated with the decorator
+            """
             for dec in self.decorators:
                 if dec.decorator is decorator:
                     return True

aspyx/threading/__init__.py

@@ -0,0 +1,10 @@
+"""
+threading utilities
+"""
+from .thread_local import ThreadLocal
+
+imports = [ThreadLocal]
+
+__all__ = [
+    "ThreadLocal",
+]

aspyx/threading/thread_local.py

@@ -0,0 +1,47 @@
+"""
+Some threading related utilities.
+"""
+
+import threading
+
+from typing import Callable, Optional, TypeVar, Generic
+
+T = TypeVar("T")
+class ThreadLocal(Generic[T]):
+    """
+    A thread local value holder
+    """
+    # constructor
+
+    def __init__(self, default_factory: Optional[Callable[[], T]] = None):
+        self.local = threading.local()
+        self.factory = default_factory
+
+    # public
+
+    def get(self) -> Optional[T]:
+        """
+        return the current value or invoke the optional factory to compute one
+        :return: the value associated with the current thread
+        """
+        if not hasattr(self.local, "value"):
+            if self.factory is not None:
+                self.local.value = self.factory()
+            else:
+                return None
+
+        return self.local.value
+
+    def set(self, value: T) -> None:
+        """
+        set a value in the current thread
+        :param value: the value
+        """
+        self.local.value = value
+
+    def clear(self) -> None:
+        """
+        clear the value in the current thread
+        """
+        if hasattr(self.local, "value"):
+            del self.local.value

aspyx/{di/util → util}/stringbuilder.py

@@ -2,6 +2,9 @@
 Utility class for Java lovers
 """
 class StringBuilder:
+    """
+    A StringBuilder is used to build a string by multiple append calls.
+    """
     ___slots__ = ("_parts",)
 
     # constructor
@@ -12,6 +15,11 @@ class StringBuilder:
     # public
 
     def append(self, s: str) -> "StringBuilder":
+        """
+        append a string to the end of the string builder
+        :param s:  the string
+        :return: self
+        """
         self._parts.append(str(s))
 
         return self
@@ -23,6 +31,9 @@ class StringBuilder:
         return self
 
     def clear(self):
+        """
+        clear the content
+        """
         self._parts.clear()
 
     # object