aspyx 1.3.0__tar.gz → 1.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.3.0
+Version: 1.4.1
 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,11 +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/index/introduction)
 
-## Table of Contents
+![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)
@@ -58,85 +63,97 @@ 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
+
+- 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 and only requires a minimum initial learning curve
+
+The AOP integration, in particular, makes a lot of sense because:
 
-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 :-) 
+- 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 small python libary, that adds support for both dependency injection and aop.
+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 
+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 scopes singleton, request and thread
-- possibilty to add custom scopes
-- conditional registration of classes and factories 
-- lifecycle events methods `on_init`, `on_destroy`
-- 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 )
-- hierarchical environments
-
-With respect to aop:
+- support for eager and lazy construction
+- 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`
+- 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 
+- 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
 
 ```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:
     def __init__(self):
         pass
 
-    def hello(msg: str):
+    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
 
-# go, forrest
 
-environment = Environment(SampleEnvironment)
+# create environment
+
+environment = Environment(SampleModule)
+
+# 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,26 +166,19 @@ 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()
 ```
 
-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
 
@@ -196,8 +206,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!
 
@@ -272,19 +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.
+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.
 
@@ -297,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
 ```
@@ -320,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.
@@ -344,7 +362,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 +375,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 +410,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 +428,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 +445,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 +470,64 @@ 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. 
+
+On the other hand, advices are also regular DI objects, as they will usually require some kind of - injected - context.
 
-Advice classes need to be part of classes that add a `@advice()` decorator and can define methods that add aspects.
+Advices are regular classes decorated with `@advice` that define aspect methods.
 
 ```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`)
+
+⚠️ **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.
 
-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 +535,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 +560,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 +570,29 @@ 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!
+
+## Advice Lifecycle and visibility.
 
-A handy decorator `@synchronized` is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
+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.
+
+**Example**:
+```python
+@injectable()
+class Foo:
+    def __init__(self):
+        pass
+
+    @synchronized()
+    def execute_synchronized(self):
+        ...
+```
 
 # Configuration 
 
@@ -561,9 +609,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):
@@ -620,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):
@@ -640,7 +688,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 +704,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 +728,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
+
+@module()
+class SampleModule:
+    # 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 +825,20 @@ def transactional(scope):
 
 - added `YamlConfigurationSource`
 
-**1.2.1**
+**1.3.0**
+
+- added `@conditional`
+- added support for `async` advices
+
+
+**1.4.0**
+
+- bugfixes
+- added `@ExceptionManager`
+
+**1.4.1**
+
+- mkdocs