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

aspyx/di/__init__.py

@@ -1,7 +1,7 @@
 """
 This module provides dependency injection and aop capabilities for Python applications.
 """
-from .di import conditional, requires_class, requires_feature, DIException, AbstractCallableProcessor, LifecycleCallable, Lifecycle, Providers, Environment, ClassInstanceProvider, injectable, factory, environment, inject, order, create, on_init, on_running, on_destroy, inject_environment, Factory, PostProcessor
+from .di import conditional, requires_class, requires_feature, DIException, AbstractCallableProcessor, LifecycleCallable, Lifecycle, Providers, Environment, ClassInstanceProvider, injectable, factory, module, inject, order, create, on_init, on_running, on_destroy, inject_environment, Factory, PostProcessor
 
 # import something from the subpackages, so that the decorators are executed
 
@@ -17,7 +17,7 @@ __all__ = [
     "Environment",
     "injectable",
     "factory",
-    "environment",
+    "module",
     "inject",
     "create",
     "order",

aspyx/di/aop/__init__.py

@@ -1,7 +1,20 @@
 """
-AOP module
+The AOP module gives you the possibility to define aspects that will participate in method execution flows.
+
+**Example**: all method executions of methods named "foo" will include a `before` aspect, that will be executed before the original method
+
+```python
+@advice
+class Advice:
+   @before(methods().named("foo"))
+   def before_call(self, invocation: Invocation):
+      ...
+
+```
+
+Note, that this requires that both the advice and the targeted methods need to be managed by an environment.
 """
-from .aop import before, after, classes, around, error, advice, methods, Invocation
+from .aop import before, after, classes, around, error, advice, methods, Invocation, AspectTarget
 __all__ = [
     "before",
     "after",
@@ -11,4 +24,5 @@ __all__ = [
     "classes",
     "methods",
     "Invocation",
+    "AspectTarget"
 ]

aspyx/di/aop/aop.py

@@ -25,6 +25,7 @@ class AspectType(Enum):
     AspectType defines the types of aspect-oriented advice that can be applied to methods.
 
     The available types are:
+
     - BEFORE: Advice to be executed before the method invocation.
     - AROUND: Advice that intercepts the method invocation.
     - AFTER: Advice to be executed after the method invocation, regardless of its outcome.
@@ -98,7 +99,7 @@ class AspectTarget(ABC):
 
      # fluent
 
-    def function(self, func):
+    def function(self, func) -> AspectTarget:
         self._function = func
         return self
 
@@ -107,39 +108,65 @@ class AspectTarget(ABC):
 
         return self
 
-    def that_are_async(self):
+    def that_are_async(self) -> AspectTarget:
         """
         matches methods that are async
-        :return: self
+
+        Returns:
+            AspectTarget: self
         """
         self._async = True
         return self
 
-    def of_type(self, type: Type):
+    def of_type(self, type: Type) -> AspectTarget:
         """
         matches methods belonging to a class or classes that are subclasses of the specified type
-        :return: self
+
+        Args:
+            type (Type): the type to match against
+
+        Returns:
+            AspectTarget: self
         """
         self.types.append(type)
         return self
 
-    def decorated_with(self, decorator):
+    def decorated_with(self, decorator: Callable) -> AspectTarget:
         """
         matches methods or classes that are decorated with the specified decorator
-        :param decorator:  the decorator callable
-        :return:
+
+        Args:
+            decorator (Callable): the decorator callable
+
+        Returns:
+            AspectTarget: self
         """
         self.decorators.append(decorator)
         return self
 
-    def matches(self, pattern: str):
+    def matches(self, pattern: str) -> AspectTarget:
         """
         Matches the target against a pattern.
+
+        Args:
+            pattern (str): the pattern
+
+        Returns:
+            AspectTarget: self
         """
         self.patterns.append(re.compile(pattern))
         return self
 
-    def named(self, name: str):
+    def named(self, name: str) -> AspectTarget:
+        """
+        Matches the target against a name.
+
+        Args:
+            name (str): the name
+
+        Returns:
+            AspectTarget: self
+        """
         self.names.append(name)
         return self
 
@@ -234,15 +261,21 @@ class MethodAspectTarget(AspectTarget):
 
         return True
 
-def methods():
+def methods() -> AspectTarget:
     """
     Create a new AspectTarget instance to define method aspect targets.
+
+    Returns:
+         AspectTarget: the method target
     """
     return MethodAspectTarget()
 
-def classes():
+def classes() -> AspectTarget:
     """
     Create a new AspectTarget instance to define class aspect targets.
+
+    Returns:
+        AspectTarget: the method target
     """
     return ClassAspectTarget()
 
@@ -405,7 +438,7 @@ class Invocation:
 
     def proceed(self, *args, **kwargs):
         """
-        Proceed to the next join point in the around chain up to the original method.
+        Proceed to the next aspect in the around chain up to the original method.
         """
         if len(args) > 0 or len(kwargs) > 0:  # as soon as we have args, we replace the current ones
             self.args = args
@@ -417,7 +450,7 @@ class Invocation:
 
     async def proceed_async(self, *args, **kwargs):
         """
-        Proceed to the next join point in the around chain up to the original method.
+        Proceed to the next aspect in the around chain up to the original method.
         """
         if len(args) > 0 or len(kwargs) > 0:  # as soon as we have args, we replace the current ones
             self.args = args
@@ -428,6 +461,9 @@ class Invocation:
         return await self.current_aspect.next.call_async(self)
 
 class Advices:
+    """
+    Internal utility class that collects all advice s
+    """
     # static data
 
     targets: list[AspectTarget] = []
@@ -443,7 +479,13 @@ class Advices:
 
     @classmethod
     def collect(cls, clazz, member, type: AspectType, environment: Environment):
-        aspects = [FunctionAspect(environment.get(target._clazz), target._function, None) for target in Advices.targets if target._type == type and target._clazz is not clazz and environment.providers.get(target._clazz) is not None and target._matches(clazz, member)]
+        aspects = [
+            FunctionAspect(environment.get(target._clazz), target._function, None) for target in Advices.targets
+            if target._type == type
+               and target._clazz is not clazz
+               and environment.providers.get(target._clazz) is not None
+               and target._matches(clazz, member)
+        ]
 
         # sort according to order
 
@@ -518,8 +560,8 @@ def sanity_check(clazz: Type, name: str):
 
 def advice(cls):
     """
-    Classes decorated with @advice are treated as advice classes.
-    They can contain methods decorated with @before, @after, @around, or @error to define aspects.
+    Classes decorated with `@advice` are treated as advice classes.
+    They can contain methods decorated with `@before`, `@after`, `@around`, or `@error` to define aspects.
     """
     Providers.register(ClassInstanceProvider(cls, True))
 
@@ -528,7 +570,7 @@ def advice(cls):
     for name, member in TypeDescriptor.for_type(cls).methods.items():
         decorator = next((decorator for decorator in member.decorators if decorator.decorator in [before, after, around, error]), None)
         if decorator is not None:
-            target = decorator.args[0] # ? ...?? TODO, can be multiple
+            target = decorator.args[0] # multiple targets are already merged in a single! check _register
             target._clazz = cls
             sanity_check(cls, name)
             Advices.targets.append(target) #??
@@ -550,7 +592,7 @@ def _register(decorator, targets: list[AspectTarget], func, aspect_type: AspectT
 
 def before(*targets: AspectTarget):
     """
-    Methods decorated with @before will be executed before the target method is invoked.
+    Methods decorated with `@before` will be executed before the target method is invoked.
     """
     def decorator(func):
         _register(before, targets, func, AspectType.BEFORE)
@@ -561,7 +603,7 @@ def before(*targets: AspectTarget):
 
 def error(*targets: AspectTarget):
     """
-    Methods decorated with @error will be executed if the target method raises an exception."""
+    Methods decorated with `@error` will be executed if the target method raises an exception."""
     def decorator(func):
         _register(error, targets, func, AspectType.ERROR)
 
@@ -571,7 +613,7 @@ def error(*targets: AspectTarget):
 
 def after(*targets: AspectTarget):
     """
-    Methods decorated with @after will be executed after the target method is invoked.
+    Methods decorated with `@after` will be executed after the target method is invoked.
     """
     def decorator(func):
         _register(after, targets, func, AspectType.AFTER)
@@ -582,7 +624,7 @@ def after(*targets: AspectTarget):
 
 def around(*targets: AspectTarget):
     """
-    Methods decorated with @around will be executed around the target method.
+    Methods decorated with `@around` will be executed around the target method.
     Every around method must accept a single parameter of type Invocation and needs to call proceed
     on this parameter to proceed to the next around method.
     """

aspyx/di/configuration/__init__.py

@@ -1,7 +1,7 @@
 """
-Configuration value handling
+This module contains functionality to read configuration values from different sources and to retrieve or inject them.
 """
-from .configuration import ConfigurationManager, ConfigurationSource, value
+from .configuration import ConfigurationManager, ConfigurationSource, inject_value
 from .env_configuration_source import EnvConfigurationSource
 from .yaml_configuration_source import YamlConfigurationSource
 
@@ -10,5 +10,5 @@ __all__ = [
     "ConfigurationSource",
     "EnvConfigurationSource",
     "YamlConfigurationSource",
-    "value"
+    "inject_value"
 ]

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

@@ -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()
@@ -362,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__)
@@ -449,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__ = []
@@ -740,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)
@@ -754,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)
@@ -763,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
@@ -772,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
@@ -781,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)
@@ -789,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
@@ -873,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
 
@@ -987,7 +1062,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")
 
@@ -1136,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:
@@ -1413,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/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
 
@@ -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

@@ -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

@@ -32,20 +32,44 @@ class Decorators:
     Utility class that caches decorators ( Python does not have a feature for this )
     """
     @classmethod
-    def add(cls, func, decorator: Callable, *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 has_decorator(cls, func, callable: Callable) -> bool:
-        return any(decorator.decorator is callable for decorator in Decorators.get(func))
+    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) -> list[DecoratorDescriptor]:
-        return getattr(func, '__decorators__', [])
+    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:
     """
@@ -79,30 +103,42 @@ class TypeDescriptor:
         def get_name(self) -> str:
             """
             return the method name
-            :return: the method name
+
+            Returns:
+                str: 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
+
+            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
-            :return: async flag
+
+            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
-            :param decorator:
-            :return:  the DecoratorDescriptor or None
+
+            Args:
+                decorator: the decorator
+
+            Returns:
+                Optional[DecoratorDescriptor]: the DecoratorDescriptor or None
             """
             for dec in self.decorators:
                 if dec.decorator is decorator:
@@ -113,8 +149,12 @@ class TypeDescriptor:
         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
+
+            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:

aspyx/threading/__init__.py

@@ -1,5 +1,5 @@
 """
-threading utilities
+A module with threading related utilities
 """
 from .thread_local import ThreadLocal
 

aspyx/threading/thread_local.py

@@ -22,7 +22,9 @@ class ThreadLocal(Generic[T]):
     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
+
+        Returns:
+            Optional[T]: the value associated with the current thread
         """
         if not hasattr(self.local, "value"):
             if self.factory is not None:
@@ -35,7 +37,9 @@ class ThreadLocal(Generic[T]):
     def set(self, value: T) -> None:
         """
         set a value in the current thread
-        :param value: the value
+
+        Args:
+            value: the value
         """
         self.local.value = value
 

aspyx/util/stringbuilder.py

@@ -17,8 +17,12 @@ class StringBuilder:
     def append(self, s: str) -> "StringBuilder":
         """
         append a string to the end of the string builder
-        :param s:  the string
-        :return: self
+
+        Args:
+            s (str): the string
+
+        Returns:
+            StringBuilder: self
         """
         self._parts.append(str(s))
 

{aspyx-1.4.0.dist-info → aspyx-1.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.4.0
+Version: 1.4.1
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -40,12 +40,14 @@ Dynamic: license-file
 ![License](https://img.shields.io/github/license/coolsamson7/aspyx)
 ![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
 [![PyPI](https://img.shields.io/pypi/v/aspyx)](https://pypi.org/project/aspyx/)
-[![Docs](https://img.shields.io/badge/docs-online-blue?logo=github)](https://coolsamson7.github.io/aspyx/)
+[![Docs](https://img.shields.io/badge/docs-online-blue?logo=github)](https://coolsamson7.github.io/aspyx/index/introduction)
+
+![image](https://github.com/user-attachments/assets/e808210a-b1a4-4fd0-93f1-b5f9845fa520)
 
 ## Table of Contents 
 
 - [Motivation](#motivation)
-- [Introduction](#introduction)
+- [Overview](#overview)
 - [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
@@ -71,16 +73,19 @@ Dynamic: license-file
 
 While working on AI-related projects in Python, I was looking for a dependency injection (DI) framework. After evaluating existing options, my impression was that the most either lacked key features — such as integrated AOP — or had APIs that felt overly technical and complex, which made me develop a library on my own with the following goals
 
-- bring both di and AOP features together in a lightweight library,
+- bring both di and AOP features together in a lightweight library ( still only about 2T loc),
 - be as minimal invasive as possible,
 - offering mechanisms to easily extend and customize features without touching the core,
-- while still offering a _simple_ and _readable_ api that doesnt overwhelm developers
+- while still offering a _simple_ and _readable_ api that doesnt overwhelm developers and only requires a minimum initial learning curve
+
+The AOP integration, in particular, makes a lot of sense because:
 
-Especially the AOP integration definitely makes sense, as aspects on their own also usually require a context, which in a DI world is simply injected.
+- Aspects typically require context, which is naturally provided through DI,
+- And they should only apply to objects managed by the container, rather than acting globally.
 
-# Introduction
+# Overview
 
-Aspyx is a lightweight Python library that provides both Dependency Injection (DI) and Aspect-Oriented Programming (AOP) support.
+Aspyx is a lightweight - still only about 2T LOC- Python library that provides both Dependency Injection (DI) and Aspect-Oriented Programming (AOP) support.
 
 The following DI features are supported 
 - constructor and setter injection
@@ -89,13 +94,13 @@ The following DI features are supported
 - post processors
 - support for factory classes and methods
 - support for eager and lazy construction
-- support for scopes singleton, request and thread
+- support for scopes "singleton", "request" and "thread"
 - possibility to add custom scopes
 - conditional registration of classes and factories ( aka profiles in spring )
 - lifecycle events methods `on_init`, `on_destroy`, `on_running`
-- bundling of injectable objects according to their module location including recursive imports and inheritance
-- instantiation of - possibly multiple - container instances - so called environments - that manage the lifecycle of related objects
-- hierarchical environments
+- Automatic discovery and bundling of injectable objects based on their module location, including support for recursive imports
+- Instantiation of one or possible more isolated container instances — called environments — each managing the lifecycle of a related set of objects,
+ - Support for hierarchical environments, enabling structured scoping and layered object management.
 
 With respect to AOP:
 - support for before, around, after and error aspects 
@@ -107,7 +112,8 @@ The library is thread-safe and heavily performance optimized as most of the runt
 Let's look at a simple example
 
 ```python
-from aspyx.di import injectable, on_init, on_destroy, environment, Environment
+from aspyx.di import injectable, on_init, on_destroy, module, Environment
+
 
 @injectable()
 class Foo:
@@ -117,27 +123,28 @@ class Foo:
     def hello(self, msg: str):
         print(f"hello {msg}")
 
+
 @injectable()  # eager and singleton by default
 class Bar:
-    def __init__(self, foo: Foo): # will inject the Foo dependency
+    def __init__(self, foo: Foo):  # will inject the Foo dependency
         self.foo = foo
 
-    @on_init() # a lifecycle callback called after the constructor and all possible injections
+    @on_init()  # a lifecycle callback called after the constructor and all possible injections
     def init(self):
         ...
 
 
-# this class will register all - specifically decorated - classes and factories in the own module
-# In this case Foo and Bar
+# this class will discover and manage all - specifically decorated - classes and factories that are part of the own module
 
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     def __init__(self):
         pass
 
+
 # create environment
 
-environment = Environment(SampleEnvironment)
+environment = Environment(SampleModule)
 
 # fetch an instance
 
@@ -171,12 +178,7 @@ class SampleAdvice:
         return invocation.proceed()
 ```
 
-The invocation parameter stores the complete context of the current execution, which are
-- the method
-- args
-- kwargs
-- the result
-- the possible caught error
+While features like DI and AOP are often associated with enterprise applcations, this example hopefully demonstrates that they work just as well in small- to medium-sized projects—without introducing significant overhead—while still providing powerful tools for achieving clean architecture, resulting in maintainable and easily testable code.
 
 Let's look at the details
 
@@ -280,21 +282,26 @@ Valid conditions are created by:
 
 ## Definition
 
-An `Environment` is the container that manages the lifecycle of objects. The set of classes and instances is determined by a constructor argument that controls the class registry.
+An `Environment` is the container that manages the lifecycle of objects. 
+The set of classes and instances is determined by a 
+constructor type argument called `module`.
 
 **Example**: 
 ```python
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     def __init__(self):
         pass
-
-environment = Environment(SampleEnvironment)
 ```
 
-The default is that all eligible classes, that are implemented in the containing module or in any submodule will be managed.
-THe container will import the module and its children automatically. No need to add artificial import statements!
+A module is a regular injectable class decorated with `@module` that controls the discovery of injectable classes, by filtering classes according to their module location relative to this class. 
+  All eligible classes, that are implemented in the containing module or in any submodule will be managed.
 
+In a second step the real container - the environment - is created based on a module:
+
+```python
+environment = Environment(SampleModule, features=["dev"])
+```
 
 By adding the parameter `features: list[str]`, it is possible to filter injectables by evaluating the corresponding `@conditional` decorators.
 
@@ -307,21 +314,21 @@ class DevOnly:
      def __init__(self):
         pass
 
-@environment()
-class SampleEnvironmen():
+@module()
+class SampleModule():
     def __init__(self):
         pass
 
-environment = Environment(SampleEnvironment, features=["dev"])
+environment = Environment(SampleModule, features=["dev"])
 ```
 
 
-By adding an `imports: list[Type]` parameter, specifying other environment types, it will register the appropriate classes recursively.
+By adding an `imports: list[Type]` parameter, specifying other module types, it will register the appropriate classes recursively.
 
 **Example**: 
 ```python
-@environment()
-class SampleEnvironmen(imports=[OtherEnvironment]):
+@module()
+class SampleModule(imports=[OtherModule]):
     def __init__(self):
         pass
 ```
@@ -330,8 +337,9 @@ Another possibility is to add a parent environment as an `Environment` construct
 
 **Example**: 
 ```python
-rootEnvironment = Environment(RootEnvironment)
-environment = Environment(SampleEnvironment, parent=rootEnvironment)
+rootEnvironment = Environment(RootModule)
+
+environment = Environment(SampleModule, parent=rootEnvironment)
 ```
 
 The difference is, that in the first case, class instances of imported modules will be created in the scope of the _own_ environment, while in the second case, it will return instances managed by the parent.
@@ -464,7 +472,9 @@ class SingletonScope(Scope):
 
 It is possible to define different aspects, that will be part of method calling flow. This logic fits nicely in the library, since the DI framework controls the instantiation logic and can handle aspects within a regular post processor. 
 
-Advice classes need to be part of classes that add a `@advice()` decorator and can define methods that add aspects.
+On the other hand, advices are also regular DI objects, as they will usually require some kind of - injected - context.
+
+Advices are regular classes decorated with `@advice` that define aspect methods.
 
 ```python
 @advice
@@ -516,7 +526,7 @@ All methods are expected to have single `Invocation` parameter, that stores
 - `result` the result ( initially `None`)
 - `exception` a possible caught exception ( initially `None`)
 
-⚠️ **Attention:** It is essential for `around` methods to call `proceed()` on the invocation, which will call the next around method in the chain and finally the original method.
+⚠️ **Note:** It is essential for `around` methods to call `proceed()` on the invocation, which will call the next around method in the chain and finally the original method.
 
 If the `proceed` is called with parameters, they will replace the original parameters! 
 
@@ -562,6 +572,12 @@ class TransactionAdvice:
 
 With respect to async methods, you need to make sure, to replace a `proceed()` with a `await proceed_async()` to have the overall chain async!
 
+## Advice Lifecycle and visibility.
+
+Advices are always part of a specific environment, and only modify methods of objects managed by exactly this environment.
+
+An advice of a parent environment will for example not see classes of inherited environments. What is done instead, is to recreate the advice - more technically speaking, a processor that will collect and apply the advices -  in every child environment, and let it operate on the local objects. With this approach different environments are completely isolated from each other with no side effects whatsoever.   
+
 # Threading
 
 A handy decorator `@synchronized` in combination with the respective advice is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
@@ -652,8 +668,8 @@ Two specific source are already implemented:
 Typically you create the required configuration sources in an environment class, e.g.
 
 ```python
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     # constructor
 
     def __init__(self):
@@ -725,8 +741,8 @@ class DerivedException(Exception):
     def __init__(self):
         pass
 
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     # constructor
 
     def __init__(self):
@@ -820,6 +836,10 @@ class ExceptionAdvice:
 - bugfixes
 - added `@ExceptionManager`
 
+**1.4.1**
+
+- mkdocs
+
 
       
 

aspyx-1.4.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+aspyx/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aspyx/di/__init__.py,sha256=BDOloIhmCIUJWC7l4PLtuiWS1LlWyitIofLCLcyXYpQ,1097
+aspyx/di/di.py,sha256=ozZanDcrmluzghQBqqD_vbav3Civ-V4R8XXwlBAM3MI,44068
+aspyx/di/aop/__init__.py,sha256=rn6LSpzFtUOlgaBATyhLRWBzFmZ6XoVKA9B8SgQzYEI,746
+aspyx/di/aop/aop.py,sha256=Cn-fqFW6PznVDM38fPX7mqlSpjGKMsgpJRBSYBv59xY,18403
+aspyx/di/configuration/__init__.py,sha256=flM9A79J2wfA5I8goQbxs4tTqYustR9tn_9s0YO2WJQ,484
+aspyx/di/configuration/configuration.py,sha256=cXW40bPXiUZ9hUtBoZkSATT3nLrDPWsSqxtgASIBQaM,4375
+aspyx/di/configuration/env_configuration_source.py,sha256=FXPvREzq2ZER6_GG5xdpx154TQQDxZVf7LW7cvaylAk,1446
+aspyx/di/configuration/yaml_configuration_source.py,sha256=NDl3SeoLMNVlzHgfP-Ysvhco1tRew_zFnBL5gGy2WRk,550
+aspyx/di/threading/__init__.py,sha256=qrWdaq7MewQ2UmZy4J0Dn6BhY-ahfiG3xsv-EHqoqSE,191
+aspyx/di/threading/synchronized.py,sha256=BQ9PjMQUJsF5r-qWaDgvqg3AvFm_R9QZdKB49EkoelQ,1263
+aspyx/exception/__init__.py,sha256=OZwv-C3ZHD0Eg1rohCQMj575WLJ7lfYuk6PZD6sh1MA,211
+aspyx/exception/exception_manager.py,sha256=ihQ8Hs_EAUi-4xtVOn6kNZVblJjznpscLQ4vKXfWq7s,5228
+aspyx/reflection/__init__.py,sha256=r2sNJrfHDpuqaIYu4fTYsoo046gpgn4VTd7bsS3mQJY,282
+aspyx/reflection/proxy.py,sha256=kaVPeEGuerdYgcgchMe99c8xykDskRSYR-w4OF83Ofo,1868
+aspyx/reflection/reflection.py,sha256=AgChenUzK9elcqOc_BfMiszTQuXrsy0NHYkqy9Jsl0E,8066
+aspyx/threading/__init__.py,sha256=3clmbCDP37GPan3dWtxTQvpg0Ti4aFzruAbUClkHGi0,147
+aspyx/threading/thread_local.py,sha256=86dNtbA4k2B-rNUUnZgn3_pU0DAojgLrRnh8RL6zf1E,1196
+aspyx/util/__init__.py,sha256=8H2yKkXu3nkRGeTerb8ialzKGfvzUx44XUWFUYcYuQM,125
+aspyx/util/stringbuilder.py,sha256=a-0T4YEXSJFUuQ3ztKN1ZPARkh8dIGMSkNEEJHRN7dc,856
+aspyx-1.4.1.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
+aspyx-1.4.1.dist-info/METADATA,sha256=cEYH9P1Mng4RjRQID-bUp-5X6fbxUHhQWf3WDUwkPI0,26564
+aspyx-1.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aspyx-1.4.1.dist-info/top_level.txt,sha256=A_ZwhBY_ybIgjZlztd44eaOrWqkJAndiqjGlbJ3tR_I,6
+aspyx-1.4.1.dist-info/RECORD,,

aspyx-1.4.0.dist-info/RECORD

@@ -1,25 +0,0 @@
-aspyx/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aspyx/di/__init__.py,sha256=OfETLGaquTbFHhhDRzzGtnSu-KkMj68aDdEaVU19KoI,1107
-aspyx/di/di.py,sha256=qoOChsiUBla52UaclRlX6o5ZxRylaFF4IneanvwISos,42095
-aspyx/di/aop/__init__.py,sha256=nOABex49zSyMZ2w1ezwX3Q3yrOcQRSDjDtSj0DwKVbQ,233
-aspyx/di/aop/aop.py,sha256=36p3jCnNtrDL11jTi7NNpW1eGO_BqKL0s5rErsPdxps,17520
-aspyx/di/configuration/__init__.py,sha256=mweJ3tZX1YJfY1d4ra-i0TWEcF3EwXBpGbHrKg1Kc6E,380
-aspyx/di/configuration/configuration.py,sha256=KfPjrlUhhmEOUxdJiXePt5RGxKc8JczkWqlEBjpWQTg,4362
-aspyx/di/configuration/env_configuration_source.py,sha256=FXPvREzq2ZER6_GG5xdpx154TQQDxZVf7LW7cvaylAk,1446
-aspyx/di/configuration/yaml_configuration_source.py,sha256=NDl3SeoLMNVlzHgfP-Ysvhco1tRew_zFnBL5gGy2WRk,550
-aspyx/di/threading/__init__.py,sha256=qrWdaq7MewQ2UmZy4J0Dn6BhY-ahfiG3xsv-EHqoqSE,191
-aspyx/di/threading/synchronized.py,sha256=BQ9PjMQUJsF5r-qWaDgvqg3AvFm_R9QZdKB49EkoelQ,1263
-aspyx/exception/__init__.py,sha256=2Jo0a_fZK8_U9SpPZ0j4aeAXJZ28uw6g-20TH_85JqY,200
-aspyx/exception/exception_manager.py,sha256=8H5fbbcpzLxiK7OI-EZaXyX5Db4uZt9-VrAx5LMiSm8,4692
-aspyx/reflection/__init__.py,sha256=r2sNJrfHDpuqaIYu4fTYsoo046gpgn4VTd7bsS3mQJY,282
-aspyx/reflection/proxy.py,sha256=zJ6Psd6zWfFABdrKOf4cULt3gibyqCRdcR6z8WKIkzE,1982
-aspyx/reflection/reflection.py,sha256=bzH5KVJ5X5ycQu5SG7BFZtioWN7sa1w1Y-xR_Y-oN6w,7113
-aspyx/threading/__init__.py,sha256=_j_AQ4t1ecRaKIb9KCTT_EV0b7hivNML-2wV2XF7G6Y,125
-aspyx/threading/thread_local.py,sha256=nOSS2DM1rIHmzdU9_fjxaUF3oXCaRTBHwe76IdwMqC8,1158
-aspyx/util/__init__.py,sha256=8H2yKkXu3nkRGeTerb8ialzKGfvzUx44XUWFUYcYuQM,125
-aspyx/util/stringbuilder.py,sha256=L3MkHAo4CJrBXuWmaRQASIa9EAs8O_ea7EjZoLsvp08,811
-aspyx-1.4.0.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
-aspyx-1.4.0.dist-info/METADATA,sha256=S9Qcqc9v6VHJSU76dGT_iEo1Z4ghvpp8nE7uxoc2NkI,25213
-aspyx-1.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aspyx-1.4.0.dist-info/top_level.txt,sha256=A_ZwhBY_ybIgjZlztd44eaOrWqkJAndiqjGlbJ3tR_I,6
-aspyx-1.4.0.dist-info/RECORD,,