aspyx 1.3.0__tar.gz → 1.4.0__tar.gz

{aspyx-1.3.0/src/aspyx.egg-info → aspyx-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.3.0
+Version: 1.4.0
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -28,6 +28,8 @@ License: MIT License
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: mkdocstrings-python; extra == "dev"
 Dynamic: license-file
 
 # aspyx
@@ -38,8 +40,9 @@ 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/)
 
-## Table of Contents
+## Table of Contents 
 
 - [Motivation](#motivation)
 - [Introduction](#introduction)
@@ -58,43 +61,48 @@ Dynamic: license-file
   - [Post Processors](#post-processors)
 - [Custom scopes](#custom-scopes)
 - [AOP](#aop)
+- [Threading](#threading)
 - [Configuration](#configuration)
 - [Reflection](#reflection)
+- [Exceptions](#exceptions)
 - [Version History](#version-history)
 
 # Motivation
 
-While working on some AI related topics in Python, i required a simple DI framework. 
-Looking at the existing solutions - there are quite a number of - i was not quite happy. Either the solutions 
-lacked functionality - starting with that usually aop and di are separate libraries -, that i am accustomed to from other languages, or the API was in my mind too clumsy and "technical".
+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
 
-So, why not develop one on my own...Having done that in other languages previously, the task was not that hard, and last but not least...it is fun :-) 
+- bring both di and AOP features together in a lightweight library,
+- 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
+
+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.
 
 # Introduction
 
-Aspyx is a small python libary, that adds support for both dependency injection and aop.
+Aspyx is a lightweight Python library that provides both Dependency Injection (DI) and Aspect-Oriented Programming (AOP) support.
 
-The following di features are supported 
+The following DI features are supported 
 - constructor and setter injection
+- injection of configuration variables
 - possibility to define custom injections
 - post processors
 - support for factory classes and methods
-- support for eager construction
+- support for eager and lazy construction
 - support for scopes singleton, request and thread
-- possibilty to add custom scopes
-- conditional registration of classes and factories 
-- lifecycle events methods `on_init`, `on_destroy`
+- 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
-- instatiation of - possibly multiple - container instances - so called environments -  that manage the lifecylce of related objects
-- filtering of classes by associating "features" sets to environment ( similar to spring profiles )
+- instantiation of - possibly multiple - container instances - so called environments - that manage the lifecycle of related objects
 - hierarchical environments
 
-With respect to aop:
+With respect to AOP:
 - support for before, around, after and error aspects 
+- simple fluent interface to specify which methods are targeted by an aspect
 - sync and async method support
-- `synchronized` decorator that adds locking to methods
 
-The library is thread-safe!
+The library is thread-safe and heavily performance optimized as most of the runtime information is precomputed and cached!
 
 Let's look at a simple example
 
@@ -106,7 +114,7 @@ class Foo:
     def __init__(self):
         pass
 
-    def hello(msg: str):
+    def hello(self, msg: str):
         print(f"hello {msg}")
 
 @injectable()  # eager and singleton by default
@@ -127,16 +135,18 @@ class SampleEnvironment:
     def __init__(self):
         pass
 
-# go, forrest
+# create environment
 
 environment = Environment(SampleEnvironment)
 
+# fetch an instance
+
 bar = env.get(Bar)
 
 bar.foo.hello("world")
 ```
 
-The concepts should be pretty familiar as well as the names which are a combination of Spring and Angular names :-)
+The concepts should be pretty familiar as well as the names as they are inspired by both Spring and Angular.
 
 Let's add some aspects...
 
@@ -149,17 +159,15 @@ class SampleAdvice:
 
     @before(methods().named("hello").of_type(Foo))
     def call_before(self, invocation: Invocation):
-        print("before Foo.hello(...)")
+        ...
 
     @error(methods().named("hello").of_type(Foo))
     def call_error(self, invocation: Invocation):
-        print("error Foo.hello(...)")
-        print(invocation.exception)
+        ... # exception accessible in invocation.exception
 
     @around(methods().named("hello"))
     def call_around(self, invocation: Invocation):
-        print("around Foo.hello()")
-
+        ...
         return invocation.proceed()
 ```
 
@@ -196,8 +204,8 @@ class Foo:
     def __init__(self):
         pass
 ```
-Please make sure, that the class defines a local constructor, as this is required to determine injected instances. 
-All referenced types will be injected by the environemnt. 
+⚠️ **Attention:** Please make sure, that the class defines a local constructor, as this is _required_ to determine injected instances. 
+All referenced types will be injected by the environment. 
 
 Only eligible types are allowed, of course!
 
@@ -285,6 +293,8 @@ 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!
+
 
 By adding the parameter `features: list[str]`, it is possible to filter injectables by evaluating the corresponding `@conditional` decorators.
 
@@ -298,7 +308,7 @@ class DevOnly:
         pass
 
 @environment()
-class SampleEnvironmen()):
+class SampleEnvironmen():
     def __init__(self):
         pass
 
@@ -311,7 +321,7 @@ By adding an `imports: list[Type]` parameter, specifying other environment types
 **Example**: 
 ```python
 @environment()
-class SampleEnvironmen(imports=[OtherEnvironment])):
+class SampleEnvironmen(imports=[OtherEnvironment]):
     def __init__(self):
         pass
 ```
@@ -344,7 +354,7 @@ The container knows about class hierarchies and is able to `get` base classes, a
 
 In case of ambiguities, it will throw an exception.
 
-Please be aware, that a base class are not _required_ to be annotated with `@injectable`, as this would mean, that it could be created on its own as well. ( Which is possible as well, btw. ) 
+Note that a base class are not _required_ to be annotated with `@injectable`, as this would mean, that it could be created on its own as well. ( Which is possible as well, btw. ) 
 
 # Instantiation logic
 
@@ -357,7 +367,7 @@ Constructing a new instance involves a number of steps executed in this order
   different decorators can mark methods that should be called during the lifecycle ( here the construction ) of an instance.
   These are various injection possibilities as well as an optional final `on_init` call
 - PostProcessors  
-  Any custom post processors, that can add isde effects or modify the instances
+  Any custom post processors, that can add side effects or modify the instances
 
 ## Injection methods
 
@@ -392,7 +402,7 @@ It is possible to mark specific lifecyle methods.
 - `@on_init()` 
    called after the constructor and all other injections.
 - `@on_running()` 
-   called an environment has initialized all eager objects.
+   called after an environment has initialized completely ( e.g. created all eager objects ).
 - `@on_destroy()` 
    called during shutdown of the environment
 
@@ -410,7 +420,7 @@ class SamplePostProcessor(PostProcessor):
 
 Any implementing class of `PostProcessor` that is eligible for injection will be called by passing the new instance.
 
-Please be aware, that a post processor will only handle instances _after_ its _own_ registration.
+Note that a post processor will only handle instances _after_ its _own_ registration.
 
 As injectables within a single file will be handled in the order as they are declared, a post processor will only take effect for all classes after its declaration!
 
@@ -427,7 +437,7 @@ def get(self, provider: AbstractInstanceProvider, environment: Environment, argP
 Arguments are:
 - `provider` the actual provider that will create an instance
 - `environment`the requesting environment
-- `argPovider` a function that can be called to compute the required arguments recursively
+- `argProvider` a function that can be called to compute the required arguments recursively
 
 **Example**: The simplified code of the singleton provider ( disregarding locking logic )
 
@@ -452,52 +462,62 @@ class SingletonScope(Scope):
 
 # AOP
 
-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. 
+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.
 
 ```python
-@advice()
+@advice
 class SampleAdvice:
     def __init__(self):  # could inject dependencies
         pass
 
     @before(methods().named("hello").of_type(Foo))
     def call_before(self, invocation: Invocation):
-        # arguments: invocation.args
-        print("before Foo.hello(...)")
+        # arguments: invocation.args and invocation.kwargs
+        ...
+
+     @after(methods().named("hello").of_type(Foo))
+    def call_after(self, invocation: Invocation):
+        # arguments: invocation.args and invocation.kwargs
+        ...
 
     @error(methods().named("hello").of_type(Foo))
     def call_error(self, invocation: Invocation):
-        print("error Foo.hello(...)")
-        print(invocation.exception)
+         # error: invocation.exception
+        ...
 
     @around(methods().named("hello"))
     def call_around(self, invocation: Invocation):
-        print("around Foo.hello()")
-
-        return invocation.proceed()  # will leave a result in invocation.result or invocation.exception in case of an exception
+        try:
+            ...
+            return invocation.proceed()  # will leave a result in invocation.result or invocation.exception in case of an exception
+        finally:
+            ...
 ```
 
 Different aspects - with the appropriate decorator - are possible:
 - `before`  
    methods that will be executed _prior_ to the original method
 - `around`  
-   methods that will be executed _around_ to the original method giving it the possibility to add side effects or even change the parameters.
+   methods that will be executed _around_ to the original method allowing you to add side effects or even modify parameters.
 - `after`  
    methods that will be executed _after_ to the original method
 - `error`  
    methods that will be executed in case of a caught exception
 
+The different aspects can be supplemented with an `@order(<prio>)` decorator that controls the execution order based on the passed number. Smaller values get executed first. 
+
 All methods are expected to have single `Invocation` parameter, that stores
 
 - `func` the target function
-- `args` the suppliued args
+- `args` the supplied args ( including the `self` instance as the first element)
 - `kwargs` the keywords args
 - `result` the result ( initially `None`)
-- `exception` a possible caught excpetion ( 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.
 
-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! 
 
 **Example**: Parameter modifications
@@ -505,9 +525,7 @@ If the `proceed` is called with parameters, they will replace the original param
 ```python
 @around(methods().named("say"))
 def call_around(self, invocation: Invocation):
-    args = [invocation.args[0],invocation.args[1] + "!"] # 0 is self!
-
-    return invocation.proceed(*args)
+    return invocation.proceed(invocation.args[0], invocation.args[1] + "!") # 0 is self!
 ```
 
 The argument list to the corresponding decorators control which methods are targeted by the advice.
@@ -532,7 +550,7 @@ The fluent methods `named`, `matches` and `of_type` can be called multiple times
 **Example**: react on both `transactional` decorators on methods or classes
 
 ```python
-@injectable()
+@advice
 class TransactionAdvice:
     def __init__(self):
         pass
@@ -542,9 +560,23 @@ class TransactionAdvice:
         ...
 ```
 
-With respect to async methods, you need to make sure, to replace a `proceeed()` with a `await proceed_async()` to have the overall chain async!
+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!
+
+# Threading
 
-A handy decorator `@synchronized` is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
+A handy decorator `@synchronized` in combination with the respective advice is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
+
+**Example**:
+```python
+@injectable()
+class Foo:
+    def __init__(self):
+        pass
+
+    @synchronized()
+    def execute_synchronized(self):
+        ...
+```
 
 # Configuration 
 
@@ -561,9 +593,9 @@ class Foo:
         ...
 ```
 
-If required a coercion will be executed.
+If required type coercion will be applied.
 
-This concept relies on a central object `ConfigurationManager` that stores the overall configuration values as provided by so called configuration sources that are defined as follows.
+Configuration values are managed centrally using a `ConfigurationManager`, which aggregates values from various configuration sources that are defined as follows.
 
 ```python
 class ConfigurationSource(ABC):
@@ -640,7 +672,7 @@ class SampleEnvironment:
 
 As the library heavily relies on type introspection of classes and methods, a utility class `TypeDescriptor` is available that covers type information on classes. 
 
-After beeing instatiated with
+After being instantiated with
 
 ```python
 TypeDescriptor.for_type(<type>)
@@ -656,7 +688,7 @@ it offers the methods
 - `get_decorator(decorator) -> Optional[DecoratorDescriptor]`  
    return a descriptor covering the decorator. In addition to the callable, it also stores the supplied args in the `args` property
 
-The returned method descriptors offer:
+The returned method descriptors provide:
 - `param_types`  
    list of arg types
 - `return_type`  
@@ -680,6 +712,87 @@ def transactional(scope):
     return decorator
 ```
 
+# Exceptions
+
+The class `ExceptionManager` is used to collect dynamic handlers for specific exceptions and is able to dispatch to the concrete functions
+given a specific exception.
+
+The handlers are declared by annoting a class with `@exception_handler` and decorating specific methods with `@handle`
+
+**Example**:
+```python
+class DerivedException(Exception):
+    def __init__(self):
+        pass
+
+@environment()
+class SampleEnvironment:
+    # constructor
+
+    def __init__(self):
+        pass
+
+    @create()
+    def create_exception_manager(self) -> ExceptionManager:
+        return ExceptionManager()
+
+@injectable()
+@exception_handler()
+class TestExceptionHandler:
+    def __init__(self):
+        pass
+
+    @handle()
+    def handle_derived_exception(self, exception: DerivedException):
+        ExceptionManager.proceed()
+
+    @handle()
+    def handle_exception(self, exception: Exception):
+        pass
+
+    @handle()
+    def handle_base_exception(self, exception: BaseException):
+        pass
+
+
+@advice
+class ExceptionAdvice:
+    def __init__(self, exceptionManager: ExceptionManager):
+        self.exceptionManager = exceptionManager
+
+    @error(methods().of_type(Service))
+    def handle_error(self, invocation: Invocation):
+        self.exceptionManager.handle(invocation.exception)
+
+environment =  Environment(SampleEnvironment)
+
+environment.get(ExceptionManager).handle(DerivedException())
+```
+
+The exception maanger will first call the most appropriate method. 
+Any `ExceptionManager.proceed()` will in turn call the next most applicable method ( if available).
+
+Together with a simple around advice we can now add exception handling to any method:
+
+**Example**:
+```python
+@injectable()
+class Service:
+    def __init__(self):
+        pass
+
+    def throw(self):
+        raise DerivedException()
+
+@advice
+class ExceptionAdvice:
+    def __init__(self, exceptionManager: ExceptionManager):
+        self.exceptionManager = exceptionManager
+
+    @error(methods().of_type(Service))
+    def handle_error(self, invocation: Invocation):
+        self.exceptionManager.handle(invocation.exception)
+```
 
 # Version History
 
@@ -696,7 +809,16 @@ def transactional(scope):
 
 - added `YamlConfigurationSource`
 
-**1.2.1**
+**1.3.0**
+
+- added `@conditional`
+- added support for `async` advices
+
+
+**1.4.0**
+
+- bugfixes
+- added `@ExceptionManager`