aspyx 1.1.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.1.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
 
@@ -192,9 +211,9 @@ The decorator accepts the keyword arguments
  - `singleton`  
    objects are created once inside an environment and cached. This is the default.
  - `request`  
-   obejcts are created on every injection request
+   objects are created on every injection request
  - `thread`  
-   objects are cerated and cached with respect to the current thread.
+   objects are created and cached with respect to the current thread.
 
  Other scopes - e.g. session related scopes - can be defined dynamically. Please check the corresponding chapter.
 
@@ -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)`  
@@ -455,7 +529,7 @@ Both add the fluent methods:
 
 The fluent methods `named`, `matches` and `of_type` can be called multiple times!
 
-**Example**:
+**Example**: react on both `transactional` decorators on methods or classes
 
 ```python
 @injectable()
@@ -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.
@@ -478,11 +556,13 @@ class Foo:
     def __init__(self):
         pass
 
-    @value("OS")
-    def inject_value(self, os: str):
+    @inject_value("HOME")
+    def inject_home(self, os: str):
         ...
 ```
 
+If required a coercion will be executed.
+
 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.
 
 ```python
@@ -494,14 +574,24 @@ class ConfigurationSource(ABC):
 
     @abstractmethod
     def load(self) -> dict:
-        pass
 ```
 
 The `load` method is able to return a tree-like structure by returning a `dict`.
 
-As a default environment variables are already supported.
+Configuration variables are retrieved with the method
+
+```python
+def get(self, path: str, type: Type[T], default : Optional[T]=None) -> T:
+ ```
 
-Other sources can be added dynamically by just registering them.
+- `path`  
+  a '.' separated path
+- `type`  
+  the desired type
+- `default`  
+  a default, if no value is registered
+
+Sources can be added dynamically by registering them.
 
 **Example**:
 ```python
@@ -521,6 +611,31 @@ class SampleConfigurationSource(ConfigurationSource):
             }
 ```
 
+Two specific source are already implemented:
+- `EnvConfigurationSource`  
+   reads the os environment variables
+- `YamlConfigurationSource`  
+   reads a specific yaml file
+
+Typically you create the required configuration sources in an environment class, e.g.
+
+```python
+@environment()
+class SampleEnvironment:
+    # constructor
+
+    def __init__(self):
+        pass
+
+    @create()
+    def create_env_source(self) -> EnvConfigurationSource:
+        return EnvConfigurationSource()
+
+    @create()
+    def create_yaml_source(self) -> YamlConfigurationSource:
+        return YamlConfigurationSource("config.yaml")
+```
+
 # Reflection
 
 As the library heavily relies on type introspection of classes and methods, a utility class `TypeDescriptor` is available that covers type information on classes. 
@@ -537,7 +652,7 @@ it offers the methods
 - `get_method(name: str, local=False)`  
    return a single either local or overall method
 - `has_decorator(decorator: Callable) -> bool`  
-   return `True`, if the class is decorated with the specified decrator
+   return `True`, if the class is decorated with the specified decorator
 - `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
 
@@ -545,9 +660,9 @@ The returned method descriptors offer:
 - `param_types`  
    list of arg types
 - `return_type`  
-   the retur type
+   the return type
 - `has_decorator(decorator: Callable) -> bool` 
-   return `True`, if the method is decorated with the specified decrator
+   return `True`, if the method is decorated with the specified decorator
 - `get_decorator(decorator: Callable) -> Optional[DecoratorDescriptor]`  
    return a descriptor covering the decorator. In addition to the callable, it also stores the supplied args in the `args` property
 
@@ -557,9 +672,9 @@ Whenver you define a custom decorator, you will need to register it accordingly.
 
 **Example**:
 ```python
-def transactional():
+def transactional(scope):
     def decorator(func):
-        Decorators.add(func, transactional)
+        Decorators.add(func, transactional, scope) # also add _all_ parameters in order to cache them
         return func
 
     return decorator
@@ -577,6 +692,12 @@ def transactional():
 - added `@on_running()` callback
 - added `thread` scope
 
+**1.2.0**
+
+- added `YamlConfigurationSource`
+
+**1.2.1**
+
 
       
 

{aspyx-1.1.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
 
@@ -160,9 +179,9 @@ The decorator accepts the keyword arguments
  - `singleton`  
    objects are created once inside an environment and cached. This is the default.
  - `request`  
-   obejcts are created on every injection request
+   objects are created on every injection request
  - `thread`  
-   objects are cerated and cached with respect to the current thread.
+   objects are created and cached with respect to the current thread.
 
  Other scopes - e.g. session related scopes - can be defined dynamically. Please check the corresponding chapter.
 
@@ -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)`  
@@ -423,7 +497,7 @@ Both add the fluent methods:
 
 The fluent methods `named`, `matches` and `of_type` can be called multiple times!
 
-**Example**:
+**Example**: react on both `transactional` decorators on methods or classes
 
 ```python
 @injectable()
@@ -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.
@@ -446,11 +524,13 @@ class Foo:
     def __init__(self):
         pass
 
-    @value("OS")
-    def inject_value(self, os: str):
+    @inject_value("HOME")
+    def inject_home(self, os: str):
         ...
 ```
 
+If required a coercion will be executed.
+
 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.
 
 ```python
@@ -462,14 +542,24 @@ class ConfigurationSource(ABC):
 
     @abstractmethod
     def load(self) -> dict:
-        pass
 ```
 
 The `load` method is able to return a tree-like structure by returning a `dict`.
 
-As a default environment variables are already supported.
+Configuration variables are retrieved with the method
+
+```python
+def get(self, path: str, type: Type[T], default : Optional[T]=None) -> T:
+ ```
 
-Other sources can be added dynamically by just registering them.
+- `path`  
+  a '.' separated path
+- `type`  
+  the desired type
+- `default`  
+  a default, if no value is registered
+
+Sources can be added dynamically by registering them.
 
 **Example**:
 ```python
@@ -489,6 +579,31 @@ class SampleConfigurationSource(ConfigurationSource):
             }
 ```
 
+Two specific source are already implemented:
+- `EnvConfigurationSource`  
+   reads the os environment variables
+- `YamlConfigurationSource`  
+   reads a specific yaml file
+
+Typically you create the required configuration sources in an environment class, e.g.
+
+```python
+@environment()
+class SampleEnvironment:
+    # constructor
+
+    def __init__(self):
+        pass
+
+    @create()
+    def create_env_source(self) -> EnvConfigurationSource:
+        return EnvConfigurationSource()
+
+    @create()
+    def create_yaml_source(self) -> YamlConfigurationSource:
+        return YamlConfigurationSource("config.yaml")
+```
+
 # Reflection
 
 As the library heavily relies on type introspection of classes and methods, a utility class `TypeDescriptor` is available that covers type information on classes. 
@@ -505,7 +620,7 @@ it offers the methods
 - `get_method(name: str, local=False)`  
    return a single either local or overall method
 - `has_decorator(decorator: Callable) -> bool`  
-   return `True`, if the class is decorated with the specified decrator
+   return `True`, if the class is decorated with the specified decorator
 - `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
 
@@ -513,9 +628,9 @@ The returned method descriptors offer:
 - `param_types`  
    list of arg types
 - `return_type`  
-   the retur type
+   the return type
 - `has_decorator(decorator: Callable) -> bool` 
-   return `True`, if the method is decorated with the specified decrator
+   return `True`, if the method is decorated with the specified decorator
 - `get_decorator(decorator: Callable) -> Optional[DecoratorDescriptor]`  
    return a descriptor covering the decorator. In addition to the callable, it also stores the supplied args in the `args` property
 
@@ -525,9 +640,9 @@ Whenver you define a custom decorator, you will need to register it accordingly.
 
 **Example**:
 ```python
-def transactional():
+def transactional(scope):
     def decorator(func):
-        Decorators.add(func, transactional)
+        Decorators.add(func, transactional, scope) # also add _all_ parameters in order to cache them
         return func
 
     return decorator
@@ -545,6 +660,12 @@ def transactional():
 - added `@on_running()` callback
 - added `thread` scope
 
+**1.2.0**
+
+- added `YamlConfigurationSource`
+
+**1.2.1**
+
 
       
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aspyx"
-version = "1.1.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"