aspyx 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.2.0
+Version: 1.3.0
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -37,15 +37,18 @@ Dynamic: license-file
 ![Python Versions](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12-blue)
 ![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/)
 
 ## Table of Contents
 
-- [Introduction](#aspyx)
+- [Motivation](#motivation)
+- [Introduction](#introduction)
 - [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
   - [Class Factory](#class-factory)
   - [Method](#method)
+  - [Conditional](#conditional)
 - [Environment](#environment)
   - [Definition](#definition)
   - [Retrieval](#retrieval)
@@ -59,22 +62,38 @@ Dynamic: license-file
 - [Reflection](#reflection)
 - [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".
+
+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 :-) 
+
 # Introduction
 
 Aspyx is a small python libary, that adds support for both dependency injection and aop.
 
-The following features are supported 
+The following di features are supported 
 - constructor and setter injection
+- possibility to define custom injections
 - post processors
-- factory classes and methods
+- support for factory classes and methods
 - support for eager construction
-- support for singleton and request scopes
+- support for scopes singleton, request and thread
 - possibilty to add custom scopes
-- lifecycle events methods
-- bundling of injectable object sets by environment classes including recursive imports and inheritance
-- container instances that relate to environment classes and manage the lifecylce of related objects
+- 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 before, around, after and error aspects 
+- sync and async method support
+- `synchronized` decorator that adds locking to methods
+
 The library is thread-safe!
 
 Let's look at a simple example
@@ -155,11 +174,11 @@ Let's look at the details
 
 # Installation
 
-`pip install aspyx`
+Just install from PyPI with 
 
-The library is tested with all Python version > 3.9
+`pip install aspyx`
 
-Ready to go...
+The library is tested with all Python version >= 3.9
 
 # Registration
 
@@ -233,6 +252,22 @@ class Foo:
 
  The same arguments as in `@injectable` are possible.
 
+## Conditional
+
+All `@injectable` declarations can be supplemented with 
+
+```python
+@conditional(<condition>, ..., <condition>)
+```
+
+decorators that act as filters in the context of an environment.
+
+Valid conditions are created by:
+- `requires_class(clazz: Type)`  
+  the injectable is valid, if the specified class is registered as well.
+- `requires_feature(feature: str)`  
+  the injectable is valid, if the environment defines the specified feature.
+
 # Environment
 
 ## Definition
@@ -251,6 +286,26 @@ environment = Environment(SampleEnvironment)
 
 The default is that all eligible classes, that are implemented in the containing module or in any submodule will be managed.
 
+By adding the parameter `features: list[str]`, it is possible to filter injectables by evaluating the corresponding `@conditional` decorators.
+
+**Example**: 
+```python
+
+@injectable()
+@conditional(requires_feature("dev"))
+class DevOnly:
+     def __init__(self):
+        pass
+
+@environment()
+class SampleEnvironmen()):
+    def __init__(self):
+        pass
+
+environment = Environment(SampleEnvironment, features=["dev"])
+```
+
+
 By adding an `imports: list[Type]` parameter, specifying other environment types, it will register the appropriate classes recursively.
 
 **Example**: 
@@ -428,18 +483,35 @@ 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 add side effects or even change the parameters.
+   methods that will be executed _around_ to the original method giving it the possibility to add side effects or even change the parameters.
 - `after`  
-    methods that will be executed _after_ to the original method
+   methods that will be executed _after_ to the original method
 - `error`  
-   methods that will be executed in case of a caught exception, which can be retrieved by `invocation.exception`
+   methods that will be executed in case of a caught exception
+
+All methods are expected to have single `Invocation` parameter, that stores
 
-All methods are expected to hava single `Invocation` parameter, that stores, the function, args and kwargs, the return value and possible exceptions.
+- `func` the target function
+- `args` the suppliued args
+- `kwargs` the keywords args
+- `result` the result ( initially `None`)
+- `exception` a possible caught excpetion ( initially `None`)
 
 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! 
 
-The argument list to the corresponding decorators control, how aspects are associated with which methods.
+**Example**: Parameter modifications
+
+```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)
+```
+
+The argument list to the corresponding decorators control which methods are targeted by the advice.
+
 A fluent interface is used describe the mapping. 
 The parameters restrict either methods or classes and are constructed by a call to either `methods()` or `classes()`.
 
@@ -448,6 +520,8 @@ Both add the fluent methods:
    defines the matching classes
 - `named(name: str)`  
    defines method or class names
+- `that_are_async()`  
+   defines async methods
 - `matches(re: str)`  
    defines regular expressions for methods or classes
 - `decorated_with(type: Type)`  
@@ -468,6 +542,10 @@ 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!
+
+A handy decorator `@synchronized` is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
+
 # Configuration 
 
 It is possible to inject configuration values, by decorating methods with `@inject-value(<name>)` given a configuration key.
@@ -618,6 +696,8 @@ def transactional(scope):
 
 - added `YamlConfigurationSource`
 
+**1.2.1**
+
 
       
 

{aspyx-1.2.0 → aspyx-1.3.0}/README.md

@@ -5,15 +5,18 @@
 ![Python Versions](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12-blue)
 ![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/)
 
 ## Table of Contents
 
-- [Introduction](#aspyx)
+- [Motivation](#motivation)
+- [Introduction](#introduction)
 - [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
   - [Class Factory](#class-factory)
   - [Method](#method)
+  - [Conditional](#conditional)
 - [Environment](#environment)
   - [Definition](#definition)
   - [Retrieval](#retrieval)
@@ -27,22 +30,38 @@
 - [Reflection](#reflection)
 - [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".
+
+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 :-) 
+
 # Introduction
 
 Aspyx is a small python libary, that adds support for both dependency injection and aop.
 
-The following features are supported 
+The following di features are supported 
 - constructor and setter injection
+- possibility to define custom injections
 - post processors
-- factory classes and methods
+- support for factory classes and methods
 - support for eager construction
-- support for singleton and request scopes
+- support for scopes singleton, request and thread
 - possibilty to add custom scopes
-- lifecycle events methods
-- bundling of injectable object sets by environment classes including recursive imports and inheritance
-- container instances that relate to environment classes and manage the lifecylce of related objects
+- 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 before, around, after and error aspects 
+- sync and async method support
+- `synchronized` decorator that adds locking to methods
+
 The library is thread-safe!
 
 Let's look at a simple example
@@ -123,11 +142,11 @@ Let's look at the details
 
 # Installation
 
-`pip install aspyx`
+Just install from PyPI with 
 
-The library is tested with all Python version > 3.9
+`pip install aspyx`
 
-Ready to go...
+The library is tested with all Python version >= 3.9
 
 # Registration
 
@@ -201,6 +220,22 @@ class Foo:
 
  The same arguments as in `@injectable` are possible.
 
+## Conditional
+
+All `@injectable` declarations can be supplemented with 
+
+```python
+@conditional(<condition>, ..., <condition>)
+```
+
+decorators that act as filters in the context of an environment.
+
+Valid conditions are created by:
+- `requires_class(clazz: Type)`  
+  the injectable is valid, if the specified class is registered as well.
+- `requires_feature(feature: str)`  
+  the injectable is valid, if the environment defines the specified feature.
+
 # Environment
 
 ## Definition
@@ -219,6 +254,26 @@ environment = Environment(SampleEnvironment)
 
 The default is that all eligible classes, that are implemented in the containing module or in any submodule will be managed.
 
+By adding the parameter `features: list[str]`, it is possible to filter injectables by evaluating the corresponding `@conditional` decorators.
+
+**Example**: 
+```python
+
+@injectable()
+@conditional(requires_feature("dev"))
+class DevOnly:
+     def __init__(self):
+        pass
+
+@environment()
+class SampleEnvironmen()):
+    def __init__(self):
+        pass
+
+environment = Environment(SampleEnvironment, features=["dev"])
+```
+
+
 By adding an `imports: list[Type]` parameter, specifying other environment types, it will register the appropriate classes recursively.
 
 **Example**: 
@@ -396,18 +451,35 @@ 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 add side effects or even change the parameters.
+   methods that will be executed _around_ to the original method giving it the possibility to add side effects or even change the parameters.
 - `after`  
-    methods that will be executed _after_ to the original method
+   methods that will be executed _after_ to the original method
 - `error`  
-   methods that will be executed in case of a caught exception, which can be retrieved by `invocation.exception`
+   methods that will be executed in case of a caught exception
+
+All methods are expected to have single `Invocation` parameter, that stores
 
-All methods are expected to hava single `Invocation` parameter, that stores, the function, args and kwargs, the return value and possible exceptions.
+- `func` the target function
+- `args` the suppliued args
+- `kwargs` the keywords args
+- `result` the result ( initially `None`)
+- `exception` a possible caught excpetion ( initially `None`)
 
 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! 
 
-The argument list to the corresponding decorators control, how aspects are associated with which methods.
+**Example**: Parameter modifications
+
+```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)
+```
+
+The argument list to the corresponding decorators control which methods are targeted by the advice.
+
 A fluent interface is used describe the mapping. 
 The parameters restrict either methods or classes and are constructed by a call to either `methods()` or `classes()`.
 
@@ -416,6 +488,8 @@ Both add the fluent methods:
    defines the matching classes
 - `named(name: str)`  
    defines method or class names
+- `that_are_async()`  
+   defines async methods
 - `matches(re: str)`  
    defines regular expressions for methods or classes
 - `decorated_with(type: Type)`  
@@ -436,6 +510,10 @@ 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!
+
+A handy decorator `@synchronized` is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
+
 # Configuration 
 
 It is possible to inject configuration values, by decorating methods with `@inject-value(<name>)` given a configuration key.
@@ -586,6 +664,8 @@ def transactional(scope):
 
 - added `YamlConfigurationSource`
 
+**1.2.1**
+
 
       
 

{aspyx-1.2.0 → aspyx-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aspyx"
-version = "1.2.0"
+version = "1.3.0"
 description = "A DI and AOP library for Python"
 authors = [{ name = "Andreas Ernst", email = "andreas.ernst7@gmail.com" }]
 readme = "README.md"

aspyx-1.3.0/src/aspyx/di/__init__.py

@@ -0,0 +1,38 @@
+"""
+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
+
+# import something from the subpackages, so that the decorators are executed
+
+from .configuration import ConfigurationManager
+from .aop import before
+from .threading import SynchronizeAdvice
+
+imports = [ConfigurationManager, before, SynchronizeAdvice]
+
+__all__ = [
+    "ClassInstanceProvider",
+    "Providers",
+    "Environment",
+    "injectable",
+    "factory",
+    "environment",
+    "inject",
+    "create",
+    "order",
+
+    "on_init",
+    "on_running",
+    "on_destroy",
+    "inject_environment",
+    "Factory",
+    "PostProcessor",
+    "AbstractCallableProcessor",
+    "LifecycleCallable",
+    "DIException",
+    "Lifecycle",
+    "conditional",
+    "requires_class",
+    "requires_feature"
+]

{aspyx-1.2.0 → aspyx-1.3.0}/src/aspyx/di/aop/aop.py

@@ -50,7 +50,7 @@ class AspectTarget(ABC):
     __slots__ = [
         "_function",
         "_type",
-
+        "_async",
         "_clazz",
         "_instance",
         "names",
@@ -65,6 +65,7 @@ class AspectTarget(ABC):
     def __init__(self):
         self._clazz = None
         self._instance = None
+        self._async = False
         self._function = None
         self._type = None
 
@@ -108,6 +109,10 @@ class AspectTarget(ABC):
 
         return self
 
+    def that_are_async(self):
+        self._async = True
+        return self
+
     def of_type(self, type: Type):
         self.types.append(type)
         return self
@@ -178,6 +183,14 @@ class MethodAspectTarget(AspectTarget):
 
         method_descriptor = descriptor.get_method(func.__name__)
 
+        # async
+
+        name = method_descriptor.method.__name__
+        is_async = method_descriptor.is_async()
+
+        if self._async is not method_descriptor.is_async():
+            return False
+
         # type
 
         if len(self.types) > 0:
@@ -234,6 +247,9 @@ class JoinPoint:
     def call(self, invocation: 'Invocation'):
         pass
 
+    async def call_async(self, invocation: 'Invocation'):
+        pass
+
 class FunctionJoinPoint(JoinPoint):
     __slots__ = [
         "instance",
@@ -251,6 +267,11 @@ class FunctionJoinPoint(JoinPoint):
 
         return self.func(self.instance, invocation)
 
+    async def call_async(self, invocation: 'Invocation'):
+        invocation.current_join_point = self
+
+        return await self.func(self.instance, invocation)
+
 class MethodJoinPoint(FunctionJoinPoint):
     __slots__ = []
 
@@ -262,6 +283,11 @@ class MethodJoinPoint(FunctionJoinPoint):
 
         return self.func(*invocation.args, **invocation.kwargs)
 
+    async def call_async(self, invocation: 'Invocation'):
+        invocation.current_join_point = self
+
+        return await self.func(*invocation.args, **invocation.kwargs)
+
 @dataclass
 class JoinPoints:
     before: list[JoinPoint]
@@ -328,6 +354,37 @@ class Invocation:
 
         return self.result
 
+    async def call_async(self, *args, **kwargs):
+        # remember args
+
+        self.args = args
+        self.kwargs = kwargs
+
+        # run all before
+
+        for join_point in self.join_points.before:
+            join_point.call(self)
+
+        # run around's with the method being the last aspect!
+
+        try:
+            self.result = await self.join_points.around[0].call_async(self) # will follow the proceed chain
+
+        except Exception as e:
+            self.exception = e
+            for join_point in self.join_points.error:
+                join_point.call(self)
+
+        # run all before
+
+        for join_point in self.join_points.after:
+            join_point.call(self)
+
+        if self.exception is not None:
+            raise self.exception # rethrow the error
+
+        return self.result
+
     def proceed(self, *args, **kwargs):
         """
         Proceed to the next join point in the around chain up to the original method.
@@ -340,6 +397,18 @@ class Invocation:
 
         return self.current_join_point.next.call(self)
 
+    async def proceed_async(self, *args, **kwargs):
+        """
+        Proceed to the next join point 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
+            self.kwargs = kwargs
+
+        # next one please...
+
+        return await self.current_join_point.next.call_async(self)
+
 @injectable()
 class Advice:
     # static data
@@ -381,13 +450,14 @@ class Advice:
 
                 if result is None:
                     result = {}
+                    self.cache[clazz] = result
 
                     for _, member in inspect.getmembers(clazz, predicate=inspect.isfunction):
                         join_points = self.compute_join_points(clazz, member, environment)
                         if join_points is not None:
                             result[member] = join_points
 
-                    self.cache[clazz] = result
+
 
         # add around methods
 
@@ -533,10 +603,22 @@ class AdviceProcessor(PostProcessor):
     def process(self, instance: object, environment: Environment):
         join_point_dict = self.advice.join_points4(instance, environment)
 
-        for member, joinPoints in join_point_dict.items():
+        for member, join_points in join_point_dict.items():
             Environment.logger.debug("add aspects for %s:%s", type(instance), member.__name__)
 
             def wrap(jp):
-                return lambda *args, **kwargs: Invocation(member, jp).call(*args, **kwargs)
+                def sync_wrapper(*args, **kwargs):
+                    return Invocation(member, jp).call(*args, **kwargs)
+
+                return sync_wrapper
+
+            def wrap_async(jp):
+                async def async_wrapper(*args, **kwargs):
+                    return await Invocation(member, jp).call_async(*args, **kwargs)
+
+                return async_wrapper
 
-            setattr(instance, member.__name__, types.MethodType(wrap(joinPoints), instance))
+            if inspect.iscoroutinefunction(member):
+                setattr(instance, member.__name__, types.MethodType(wrap_async(join_points), instance))
+            else:
+                setattr(instance, member.__name__, types.MethodType(wrap(join_points), instance))

{aspyx-1.2.0 → aspyx-1.3.0}/src/aspyx/di/configuration/env_configuration_source.py

@@ -52,4 +52,4 @@ class EnvConfigurationSource(ConfigurationSource):
             else:
                 exploded[key] = value
 
-        return exploded
+        return exploded

{aspyx-1.2.0 → aspyx-1.3.0}/src/aspyx/di/configuration/yaml_configuration_source.py

@@ -23,4 +23,4 @@ class YamlConfigurationSource(ConfigurationSource):
 
     def load(self) -> dict:
         with open(self.file, "r") as file:
-            return yaml.safe_load(file)
+            return yaml.safe_load(file)