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

aspyx/exception/exception_manager.py

@@ -0,0 +1,185 @@
+"""
+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 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) -> BaseException:
+        result = self.handler(self.instance, exception)
+
+        if result is not None:
+            return result
+        else:
+            return 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) -> BaseException:
+        return self.handler.handle(exception)
+
+class Invocation:
+    def __init__(self, exception: BaseException, 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[Invocation]()
+
+    # class methods
+
+    @classmethod
+    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:
+            return invocation.current.handle(invocation.exception)
+        else:
+            return invocation.exception
+
+    # constructor
+
+    def __init__(self):
+        self.environment : Optional[Environment] = None
+        self.handler : list[Handler] = []
+        self.cache: Dict[Type, Chain] = {}
+        self.lock = RLock()
+
+    # 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: BaseException) -> BaseException:
+        """
+        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:
+                return chain.handle(exception)
+            finally:
+                self.invocation.clear()
+        else:
+            return exception # hmmm?

aspyx/reflection/proxy.py

@@ -14,6 +14,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,10 +23,7 @@ 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
 

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,16 +32,44 @@ class Decorators:
     Utility class that caches decorators ( Python does not have a feature for this )
     """
     @classmethod
-    def add(cls, func, decorator, *args):
-        decorators = getattr(func, '__decorators__', None)
+    def add(cls, func_or_class, decorator: Callable, *args):
+        """
+        Remember the decorator
+        Args:
+            func_or_class: a function or class
+            decorator: the decorator
+            *args: any arguments supplied to the decorator
+        """
+        decorators = getattr(func_or_class, '__decorators__', None)
         if decorators is None:
-            setattr(func, '__decorators__', [DecoratorDescriptor(decorator, *args)])
+            setattr(func_or_class, '__decorators__', [DecoratorDescriptor(decorator, *args)])
         else:
             decorators.append(DecoratorDescriptor(decorator, *args))
 
     @classmethod
-    def get(cls, func) -> list[DecoratorDescriptor]:
-        return getattr(func, '__decorators__', [])
+    def has_decorator(cls, func_or_class, callable: Callable) -> bool:
+        """
+        Return True, if the function or class is decorated with the decorator
+        Args:
+            func_or_class: a function or class
+            callable: the decorator
+
+        Returns:
+            bool: the result
+        """
+        return any(decorator.decorator is callable for decorator in Decorators.get(func_or_class))
+
+    @classmethod
+    def get(cls, func_or_class) -> list[DecoratorDescriptor]:
+        """
+        return the list of decorators associated with the given function or class
+        Args:
+            func_or_class: the function or class
+
+        Returns:
+            list[DecoratorDescriptor]: ths list
+        """
+        return getattr(func_or_class, '__decorators__', [])
 
 class TypeDescriptor:
     """
@@ -69,10 +100,46 @@ class TypeDescriptor:
 
         # public
 
+        def get_name(self) -> str:
+            """
+            return the method name
+
+            Returns:
+                str: the method name
+            """
+            return self.method.__name__
+
+        def get_doc(self, default = "") -> str:
+            """
+            return the method docstring
+
+            Args:
+                default: the default if no docstring is found
+
+            Returns:
+                str: the docstring
+            """
+            return self.method.__doc__ or default
+
         def is_async(self) -> bool:
+            """
+            return true if the method is asynchronous
+
+            Returns:
+                bool: 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
+
+            Args:
+                decorator: the decorator
+
+            Returns:
+                Optional[DecoratorDescriptor]: the DecoratorDescriptor or None
+            """
             for dec in self.decorators:
                 if dec.decorator is decorator:
                     return dec
@@ -80,6 +147,15 @@ class TypeDescriptor:
             return None
 
         def has_decorator(self, decorator: Callable) -> bool:
+            """
+            return True if the method is decorated with the decorator
+
+            Args:
+                decorator: the decorator callable
+
+            Returns:
+                bool: 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 @@
+"""
+A module with threading related utilities
+"""
+from .thread_local import ThreadLocal
+
+imports = [ThreadLocal]
+
+__all__ = [
+    "ThreadLocal",
+]

aspyx/threading/thread_local.py

@@ -0,0 +1,51 @@
+"""
+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
+
+        Returns:
+            Optional[T]: 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
+
+        Args:
+            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,15 @@ class StringBuilder:
     # public
 
     def append(self, s: str) -> "StringBuilder":
+        """
+        append a string to the end of the string builder
+
+        Args:
+            s (str): the string
+
+        Returns:
+            StringBuilder: self
+        """
         self._parts.append(str(s))
 
         return self
@@ -23,6 +35,9 @@ class StringBuilder:
         return self
 
     def clear(self):
+        """
+        clear the content
+        """
         self._parts.clear()
 
     # object