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

aspyx/di/threading/__init__.py

@@ -0,0 +1,11 @@
+"""
+threading utilities
+"""
+from .synchronized import synchronized, SynchronizeAdvice
+
+imports = [synchronized, SynchronizeAdvice]
+
+__all__ = [
+    "synchronized",
+    "SynchronizeAdvice",
+]

aspyx/di/threading/synchronized.py

@@ -0,0 +1,49 @@
+"""
+Synchronized decorator and advice
+"""
+from __future__ import annotations
+
+import threading
+from weakref import WeakKeyDictionary
+
+from aspyx.reflection import Decorators
+from aspyx.di.aop import advice, around, methods, Invocation
+
+def synchronized():
+    """
+    decorate methods to synchronize them based on an instance related `RLock`
+    """
+    def decorator(func):
+        Decorators.add(func, synchronized)
+        return func #
+
+    return decorator
+
+@advice
+class SynchronizeAdvice:
+    # constructor
+
+    def __init__(self):
+        self.locks = WeakKeyDictionary()
+
+    # internal
+
+    def get_lock(self, instance) -> threading.RLock:
+        lock = self.locks.get(instance, None)
+        if lock is None:
+            lock = threading.RLock()
+            self.locks[instance] = lock
+
+        return lock
+
+    # around
+
+    @around(methods().decorated_with(synchronized))
+    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 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,12 +12,15 @@ from weakref import WeakKeyDictionary
 
 
 class DecoratorDescriptor:
+    """
+    A DecoratorDescriptor covers the decorator - a callable - and the passed arguments
+    """
     __slots__ = [
         "decorator",
         "args"
     ]
 
-    def __init__(self, decorator, *args):
+    def __init__(self, decorator: Callable, *args):
         self.decorator = decorator
         self.args = 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,7 +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
@@ -77,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