aspyx 1.0.0__tar.gz → 1.0.1__tar.gz

{aspyx-1.0.0/src/aspyx.egg-info → aspyx-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.0.0
+Version: 1.0.1
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -25,7 +25,7 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -34,11 +34,13 @@ Dynamic: license-file
 
 ![Pylint](https://github.com/coolsamson7/aspyx/actions/workflows/pylint.yml/badge.svg)
 ![Build Status](https://github.com/coolsamson7/aspyx/actions/workflows/ci.yml/badge.svg)
-
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aspyx)
+![License](https://img.shields.io/github/license/coolsamson7/aspyx)
 
 ## Table of Contents
 
 - [Introduction](#aspyx)
+- [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
   - [Class Factory](#class-factory)
@@ -53,6 +55,7 @@ Dynamic: license-file
 - [Custom scopes](#custom-scopes)
 - [AOP](#aop)
 - [Configuration](#configuration)
+- [Reflection](#reflection)
 
 # Introduction
 
@@ -71,12 +74,13 @@ The following features are supported
 - container instances that relate to environment classes and manage the lifecylce of related objects
 - hierarchical environments
 
+The library is thread-safe!
+
 Let's look at a simple example
 
 ```python
 from aspyx.di import injectable, on_init, on_destroy, environment, Environment
 
-
 @injectable()
 class Foo:
     def __init__(self):
@@ -85,13 +89,12 @@ class Foo:
     def hello(msg: str):
         print(f"hello {msg}")
 
-
 @injectable()  # eager and singleton by default
 class Bar:
     def __init__(self, foo: Foo): # will inject the Foo dependency
         self.foo = foo
 
-    @on_init() # a lifecycle callback called  after the constructor
+    @on_init() # a lifecycle callback called after the constructor and all possible injections
     def init(self):
         ...
 
@@ -101,41 +104,40 @@ class Bar:
 
 @environment()
 class SampleEnvironment:
-    # constructor
-
     def __init__(self):
         pass
 
-
 # go, forrest
 
-environment = SampleEnvironment(Configuration)
+environment = Environment(SampleEnvironment)
 
 bar = env.get(Bar)
-bar.foo.hello("Andi")
+
+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 which are a combination of Spring and Angular names :-)
 
 Let's add some aspects...
 
 ```python
+
 @advice
 class SampleAdvice:
-    def __init__(self):
+    def __init__(self): # could inject additional stuff
         pass
 
     @before(methods().named("hello").of_type(Foo))
-    def callBefore(self, invocation: Invocation):
+    def call_before(self, invocation: Invocation):
         print("before Foo.hello(...)")
 
     @error(methods().named("hello").of_type(Foo))
-    def callError(self, invocation: Invocation):
+    def call_error(self, invocation: Invocation):
         print("error Foo.hello(...)")
         print(invocation.exception)
 
     @around(methods().named("hello"))
-    def callAround(self, invocation: Invocation):
+    def call_around(self, invocation: Invocation):
         print("around Foo.hello()")
 
         return invocation.proceed()
@@ -150,6 +152,14 @@ The invocation parameter stores the complete context of the current execution, w
 
 Let's look at the details
 
+# Installation
+
+`pip install aspyx`
+
+The library is tested with Python version > 3.8
+
+Ready to go...
+
 # Registration
 
 Different mechanisms are available that make classes eligible for injection
@@ -171,12 +181,14 @@ All referenced types will be injected by the environemnt.
 
 Only eligible types are allowed, of course!
 
+The decorator accepts the keyword arguments
+- `eager : boolean`  
+  if `True`, the container will create the instances automatically while booting the environment. This is the default.
+- `scope: str`  
+  the name of a scope which will determine how often instances will be created.
+ `singleton` will create it only once - per environment -, while `request` will recreate it on every injection request. The default is `singleton`
 
- The decorator accepts the keyword arguments
- - `eager=True` if `True`, the container will create the instances automatically while booting the environment
- - `scope="singleton"` defines how often instances will be created. `singleton` will create it only once - per environment -, while `request` will recreate it on every injection request
-
- Other scopes can be defined. Please check the corresponding chapter.
+ Other scopes - e.g. session related scopes - can be defined dynamically. Please check the corresponding chapter.
 
 ## Class Factory
 
@@ -386,17 +398,17 @@ class SampleAdvice:
         pass
 
     @before(methods().named("hello").of_type(Foo))
-    def callBefore(self, invocation: Invocation):
+    def call_before(self, invocation: Invocation):
         # arguments: invocation.args
         print("before Foo.hello(...)")
 
     @error(methods().named("hello").of_type(Foo))
-    def callError(self, invocation: Invocation):
+    def call_error(self, invocation: Invocation):
         print("error Foo.hello(...)")
         print(invocation.exception)
 
     @around(methods().named("hello"))
-    def callAround(self, invocation: Invocation):
+    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
@@ -417,7 +429,7 @@ All methods are expected to hava single `Invocation` parameter, that stores, the
 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 arguments to the corresponding decorators control, how aspects are associated with which methods.
+The argument list to the corresponding decorators control, how aspects are associated with which methods.
 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()`.
 
@@ -431,7 +443,20 @@ Both add the fluent methods:
 - `decorated_with(type: Type)`  
    defines decorators on methods or classes
 
-The fluent methods `named`, `matches` and `of_type` can be called multiple timess!
+The fluent methods `named`, `matches` and `of_type` can be called multiple times!
+
+**Example**:
+
+```python
+@injectable()
+class TransactionAdvice:
+    def __init__(self):
+        pass
+
+    @around(methods().decorated_with(transactional), classes().decorated_with(transactional))
+    def establish_transaction(self, invocation: Invocation):
+        ...
+```
 
 # Configuration 
 
@@ -452,10 +477,11 @@ This concept relies on a central object `ConfigurationManager` that stores the o
 
 ```python
 class ConfigurationSource(ABC):
-    def __init__(self, manager: ConfigurationManager):
-        manager._register(self)
+    def __init__(self):
         pass
 
+   ...
+
     @abstractmethod
     def load(self) -> dict:
         pass
@@ -467,14 +493,12 @@ As a default environment variables are already supported.
 
 Other sources can be added dynamically by just registering them.
 
+**Example**:
 ```python
 @injectable()
 class SampleConfigurationSource(ConfigurationSource):
-    # constructor
-
-    def __init__(self, manager: ConfigurationManager):
-        super().__init__(manager)
-
+    def __init__(self):
+        super().__init__()
 
     def load(self) -> dict:
         return {
@@ -487,6 +511,43 @@ class SampleConfigurationSource(ConfigurationSource):
             }
 ```
 
+# 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. 
+
+After beeing instatiated with
+
+```python
+TypeDescriptor.for_type(<type>)
+```
+
+it offers the methods
+- `get_methods(local=False)`
+- `get_method(name: str, local=False)`
+- `has_decorator(decorator) -> bool`
+- `get_decorator(decorator)`
+
+The returned method descriptors offer:
+- `param_types`
+- `return_type`
+- `has_decorator(decorator)`
+- `get_decorator(decorator)`
+
+The management of decorators in turn relies on another utility class `Decorators` that caches decorators.
+
+Whenver you define a custom decorator, you will need to register it accordingly.
+
+**Example**:
+```python
+def transactional():
+    def decorator(func):
+        Decorators.add(func, transactional)
+        return func
+
+    return decorator
+```
+
+
 
 
 

{aspyx-1.0.0 → aspyx-1.0.1}/README.md

@@ -2,11 +2,13 @@
 
 ![Pylint](https://github.com/coolsamson7/aspyx/actions/workflows/pylint.yml/badge.svg)
 ![Build Status](https://github.com/coolsamson7/aspyx/actions/workflows/ci.yml/badge.svg)
-
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aspyx)
+![License](https://img.shields.io/github/license/coolsamson7/aspyx)
 
 ## Table of Contents
 
 - [Introduction](#aspyx)
+- [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
   - [Class Factory](#class-factory)
@@ -21,6 +23,7 @@
 - [Custom scopes](#custom-scopes)
 - [AOP](#aop)
 - [Configuration](#configuration)
+- [Reflection](#reflection)
 
 # Introduction
 
@@ -39,12 +42,13 @@ The following features are supported
 - container instances that relate to environment classes and manage the lifecylce of related objects
 - hierarchical environments
 
+The library is thread-safe!
+
 Let's look at a simple example
 
 ```python
 from aspyx.di import injectable, on_init, on_destroy, environment, Environment
 
-
 @injectable()
 class Foo:
     def __init__(self):
@@ -53,13 +57,12 @@ class Foo:
     def hello(msg: str):
         print(f"hello {msg}")
 
-
 @injectable()  # eager and singleton by default
 class Bar:
     def __init__(self, foo: Foo): # will inject the Foo dependency
         self.foo = foo
 
-    @on_init() # a lifecycle callback called  after the constructor
+    @on_init() # a lifecycle callback called after the constructor and all possible injections
     def init(self):
         ...
 
@@ -69,41 +72,40 @@ class Bar:
 
 @environment()
 class SampleEnvironment:
-    # constructor
-
     def __init__(self):
         pass
 
-
 # go, forrest
 
-environment = SampleEnvironment(Configuration)
+environment = Environment(SampleEnvironment)
 
 bar = env.get(Bar)
-bar.foo.hello("Andi")
+
+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 which are a combination of Spring and Angular names :-)
 
 Let's add some aspects...
 
 ```python
+
 @advice
 class SampleAdvice:
-    def __init__(self):
+    def __init__(self): # could inject additional stuff
         pass
 
     @before(methods().named("hello").of_type(Foo))
-    def callBefore(self, invocation: Invocation):
+    def call_before(self, invocation: Invocation):
         print("before Foo.hello(...)")
 
     @error(methods().named("hello").of_type(Foo))
-    def callError(self, invocation: Invocation):
+    def call_error(self, invocation: Invocation):
         print("error Foo.hello(...)")
         print(invocation.exception)
 
     @around(methods().named("hello"))
-    def callAround(self, invocation: Invocation):
+    def call_around(self, invocation: Invocation):
         print("around Foo.hello()")
 
         return invocation.proceed()
@@ -118,6 +120,14 @@ The invocation parameter stores the complete context of the current execution, w
 
 Let's look at the details
 
+# Installation
+
+`pip install aspyx`
+
+The library is tested with Python version > 3.8
+
+Ready to go...
+
 # Registration
 
 Different mechanisms are available that make classes eligible for injection
@@ -139,12 +149,14 @@ All referenced types will be injected by the environemnt.
 
 Only eligible types are allowed, of course!
 
+The decorator accepts the keyword arguments
+- `eager : boolean`  
+  if `True`, the container will create the instances automatically while booting the environment. This is the default.
+- `scope: str`  
+  the name of a scope which will determine how often instances will be created.
+ `singleton` will create it only once - per environment -, while `request` will recreate it on every injection request. The default is `singleton`
 
- The decorator accepts the keyword arguments
- - `eager=True` if `True`, the container will create the instances automatically while booting the environment
- - `scope="singleton"` defines how often instances will be created. `singleton` will create it only once - per environment -, while `request` will recreate it on every injection request
-
- Other scopes can be defined. Please check the corresponding chapter.
+ Other scopes - e.g. session related scopes - can be defined dynamically. Please check the corresponding chapter.
 
 ## Class Factory
 
@@ -354,17 +366,17 @@ class SampleAdvice:
         pass
 
     @before(methods().named("hello").of_type(Foo))
-    def callBefore(self, invocation: Invocation):
+    def call_before(self, invocation: Invocation):
         # arguments: invocation.args
         print("before Foo.hello(...)")
 
     @error(methods().named("hello").of_type(Foo))
-    def callError(self, invocation: Invocation):
+    def call_error(self, invocation: Invocation):
         print("error Foo.hello(...)")
         print(invocation.exception)
 
     @around(methods().named("hello"))
-    def callAround(self, invocation: Invocation):
+    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
@@ -385,7 +397,7 @@ All methods are expected to hava single `Invocation` parameter, that stores, the
 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 arguments to the corresponding decorators control, how aspects are associated with which methods.
+The argument list to the corresponding decorators control, how aspects are associated with which methods.
 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()`.
 
@@ -399,7 +411,20 @@ Both add the fluent methods:
 - `decorated_with(type: Type)`  
    defines decorators on methods or classes
 
-The fluent methods `named`, `matches` and `of_type` can be called multiple timess!
+The fluent methods `named`, `matches` and `of_type` can be called multiple times!
+
+**Example**:
+
+```python
+@injectable()
+class TransactionAdvice:
+    def __init__(self):
+        pass
+
+    @around(methods().decorated_with(transactional), classes().decorated_with(transactional))
+    def establish_transaction(self, invocation: Invocation):
+        ...
+```
 
 # Configuration 
 
@@ -420,10 +445,11 @@ This concept relies on a central object `ConfigurationManager` that stores the o
 
 ```python
 class ConfigurationSource(ABC):
-    def __init__(self, manager: ConfigurationManager):
-        manager._register(self)
+    def __init__(self):
         pass
 
+   ...
+
     @abstractmethod
     def load(self) -> dict:
         pass
@@ -435,14 +461,12 @@ As a default environment variables are already supported.
 
 Other sources can be added dynamically by just registering them.
 
+**Example**:
 ```python
 @injectable()
 class SampleConfigurationSource(ConfigurationSource):
-    # constructor
-
-    def __init__(self, manager: ConfigurationManager):
-        super().__init__(manager)
-
+    def __init__(self):
+        super().__init__()
 
     def load(self) -> dict:
         return {
@@ -455,6 +479,43 @@ class SampleConfigurationSource(ConfigurationSource):
             }
 ```
 
+# 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. 
+
+After beeing instatiated with
+
+```python
+TypeDescriptor.for_type(<type>)
+```
+
+it offers the methods
+- `get_methods(local=False)`
+- `get_method(name: str, local=False)`
+- `has_decorator(decorator) -> bool`
+- `get_decorator(decorator)`
+
+The returned method descriptors offer:
+- `param_types`
+- `return_type`
+- `has_decorator(decorator)`
+- `get_decorator(decorator)`
+
+The management of decorators in turn relies on another utility class `Decorators` that caches decorators.
+
+Whenver you define a custom decorator, you will need to register it accordingly.
+
+**Example**:
+```python
+def transactional():
+    def decorator(func):
+        Decorators.add(func, transactional)
+        return func
+
+    return decorator
+```
+
+
 
 
 

{aspyx-1.0.0 → aspyx-1.0.1}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aspyx"
-version = "1.0.0"
+version = "1.0.1"
 description = "A DI and AOP library for Python"
 authors = [{ name = "Andreas Ernst", email = "andreas.ernst7@gmail.com" }]
 readme = "README.md"
 license = { file = "LICENSE" }
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 dependencies = []
 
 [tool.setuptools]

{aspyx-1.0.0 → aspyx-1.0.1}/src/aspyx/di/__init__.py

@@ -1,3 +1,6 @@
+"""
+This module provides dependency injection and aop capabilities for Python applications.
+"""
 from .di import InjectorException, CallableProcessor, LifecycleCallable, Lifecycle, Providers, Environment, ClassInstanceProvider, injectable, factory, environment, inject, create, on_init, on_destroy, inject_environment, Factory, PostProcessor
 
 # import something from the subpackages, so that teh decorators are executed
@@ -26,4 +29,4 @@ __all__ = [
     "LifecycleCallable",
     "InjectorException",
     "Lifecycle"
-]
+]

{aspyx-1.0.0 → aspyx-1.0.1}/src/aspyx/di/aop/__init__.py

@@ -1,3 +1,6 @@
+"""
+AOP module
+"""
 from .aop import before, after, classes, around, error, advice, methods, Invocation
 __all__ = [
     "before",
@@ -8,4 +11,4 @@ __all__ = [
     "classes",
     "methods",
     "Invocation",
-]
+]