aspyx 1.0.1__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.0.1
+Version: 1.2.0
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -34,8 +34,9 @@ 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)
+![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)
 
 ## Table of Contents
 
@@ -56,18 +57,18 @@ Dynamic: license-file
 - [AOP](#aop)
 - [Configuration](#configuration)
 - [Reflection](#reflection)
+- [Version History](#version-history)
 
 # Introduction
 
 Aspyx is a small python libary, that adds support for both dependency injection and aop.
 
 The following features are supported 
-- constructor injection
-- method injection
+- constructor and setter injection
 - post processors
 - factory classes and methods
 - support for eager construction
-- support for singleton and reuqest scopes
+- support for singleton and request scopes
 - possibilty to add custom scopes
 - lifecycle events methods
 - bundling of injectable object sets by environment classes including recursive imports and inheritance
@@ -156,7 +157,7 @@ Let's look at the details
 
 `pip install aspyx`
 
-The library is tested with Python version > 3.8
+The library is tested with all Python version > 3.9
 
 Ready to go...
 
@@ -185,8 +186,15 @@ 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 name of a - registered - scope which will determine how often instances will be created.
+
+ The following scopes are implemented out of the box:
+ - `singleton`  
+   objects are created once inside an environment and cached. This is the default.
+ - `request`  
+   objects are created on every injection request
+ - `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.
 
@@ -304,7 +312,7 @@ Different decorators are implemented, that call methods with computed values
    the method is called with all resolved parameter types ( same as the constructor call)
 - `@inject_environment`  
    the method is called with the creating environment as a single parameter
-- `@value()`  
+- `@inject_value()`  
    the method is called with a resolved configuration value. Check the corresponding chapter
 
 **Example**:
@@ -325,9 +333,11 @@ class Foo:
 
 ## Lifecycle methods
 
-It is possible to mark specific lifecle methods. 
+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.
 - `@on_destroy()` 
    called during shutdown of the environment
 
@@ -445,7 +455,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()
@@ -460,7 +470,7 @@ class TransactionAdvice:
 
 # Configuration 
 
-It is possible to inject configuration values, by decorating methods with `@value(<name>)` given a configuration key.
+It is possible to inject configuration values, by decorating methods with `@inject-value(<name>)` given a configuration key.
 
 ```python
 @injectable()
@@ -468,11 +478,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
@@ -484,14 +496,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:
+ ```
+
+- `path`  
+  a '.' separated path
+- `type`  
+  the desired type
+- `default`  
+  a default, if no value is registered
 
-Other sources can be added dynamically by just registering them.
+Sources can be added dynamically by registering them.
 
 **Example**:
 ```python
@@ -511,6 +533,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. 
@@ -522,16 +569,24 @@ 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)`
+- `get_methods(local=False)`  
+   return a list of either local or overall 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 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
 
 The returned method descriptors offer:
-- `param_types`
-- `return_type`
-- `has_decorator(decorator)`
-- `get_decorator(decorator)`
+- `param_types`  
+   list of arg types
+- `return_type`  
+   the return type
+- `has_decorator(decorator: Callable) -> bool` 
+   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
 
 The management of decorators in turn relies on another utility class `Decorators` that caches decorators.
 
@@ -539,16 +594,29 @@ 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
 ```
 
 
+# Version History
+
+**1.0.1**
+
+- some internal refactorings
+
+**1.1.0**
+
+- added `@on_running()` callback
+- added `thread` scope
+
+**1.2.0**
 
+- added `YamlConfigurationSource`
 
 
       

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

@@ -2,8 +2,9 @@
 
 ![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)
+![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)
 
 ## Table of Contents
 
@@ -24,18 +25,18 @@
 - [AOP](#aop)
 - [Configuration](#configuration)
 - [Reflection](#reflection)
+- [Version History](#version-history)
 
 # Introduction
 
 Aspyx is a small python libary, that adds support for both dependency injection and aop.
 
 The following features are supported 
-- constructor injection
-- method injection
+- constructor and setter injection
 - post processors
 - factory classes and methods
 - support for eager construction
-- support for singleton and reuqest scopes
+- support for singleton and request scopes
 - possibilty to add custom scopes
 - lifecycle events methods
 - bundling of injectable object sets by environment classes including recursive imports and inheritance
@@ -124,7 +125,7 @@ Let's look at the details
 
 `pip install aspyx`
 
-The library is tested with Python version > 3.8
+The library is tested with all Python version > 3.9
 
 Ready to go...
 
@@ -153,8 +154,15 @@ 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 name of a - registered - scope which will determine how often instances will be created.
+
+ The following scopes are implemented out of the box:
+ - `singleton`  
+   objects are created once inside an environment and cached. This is the default.
+ - `request`  
+   objects are created on every injection request
+ - `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.
 
@@ -272,7 +280,7 @@ Different decorators are implemented, that call methods with computed values
    the method is called with all resolved parameter types ( same as the constructor call)
 - `@inject_environment`  
    the method is called with the creating environment as a single parameter
-- `@value()`  
+- `@inject_value()`  
    the method is called with a resolved configuration value. Check the corresponding chapter
 
 **Example**:
@@ -293,9 +301,11 @@ class Foo:
 
 ## Lifecycle methods
 
-It is possible to mark specific lifecle methods. 
+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.
 - `@on_destroy()` 
    called during shutdown of the environment
 
@@ -413,7 +423,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()
@@ -428,7 +438,7 @@ class TransactionAdvice:
 
 # Configuration 
 
-It is possible to inject configuration values, by decorating methods with `@value(<name>)` given a configuration key.
+It is possible to inject configuration values, by decorating methods with `@inject-value(<name>)` given a configuration key.
 
 ```python
 @injectable()
@@ -436,11 +446,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
@@ -452,14 +464,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:
+ ```
+
+- `path`  
+  a '.' separated path
+- `type`  
+  the desired type
+- `default`  
+  a default, if no value is registered
 
-Other sources can be added dynamically by just registering them.
+Sources can be added dynamically by registering them.
 
 **Example**:
 ```python
@@ -479,6 +501,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. 
@@ -490,16 +537,24 @@ 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)`
+- `get_methods(local=False)`  
+   return a list of either local or overall 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 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
 
 The returned method descriptors offer:
-- `param_types`
-- `return_type`
-- `has_decorator(decorator)`
-- `get_decorator(decorator)`
+- `param_types`  
+   list of arg types
+- `return_type`  
+   the return type
+- `has_decorator(decorator: Callable) -> bool` 
+   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
 
 The management of decorators in turn relies on another utility class `Decorators` that caches decorators.
 
@@ -507,16 +562,29 @@ 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
 ```
 
 
+# Version History
+
+**1.0.1**
+
+- some internal refactorings
+
+**1.1.0**
+
+- added `@on_running()` callback
+- added `thread` scope
+
+**1.2.0**
 
+- added `YamlConfigurationSource`
 
 
       

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

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

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

@@ -1,12 +1,12 @@
 """
 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
+from .di import 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 teh decorators are executed
 
-from aspyx.di.configuration import ConfigurationManager
-from aspyx.di.aop import before
+from .configuration import ConfigurationManager
+from .aop import before
 
 imports = [ConfigurationManager, before]
 
@@ -19,14 +19,16 @@ __all__ = [
     "environment",
     "inject",
     "create",
+    "order",
 
     "on_init",
+    "on_running",
     "on_destroy",
     "inject_environment",
     "Factory",
     "PostProcessor",
-    "CallableProcessor",
+    "AbstractCallableProcessor",
     "LifecycleCallable",
-    "InjectorException",
+    "DIException",
     "Lifecycle"
 ]

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

@@ -533,10 +533,10 @@ class AdviceProcessor(PostProcessor):
     def process(self, instance: object, environment: Environment):
         join_point_dict = self.advice.join_points4(instance, environment)
 
-        for member, join_points in join_point_dict.items():
+        for member, joinPoints 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)
 
-            setattr(instance, member.__name__, types.MethodType(wrap(join_points), instance))
+            setattr(instance, member.__name__, types.MethodType(wrap(joinPoints), instance))

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

@@ -1,11 +1,14 @@
 """
 Configuration value handling
 """
-from .configuration import ConfigurationManager, ConfigurationSource, EnvConfigurationSource, value
+from .configuration import ConfigurationManager, ConfigurationSource, value
+from .env_configuration_source import EnvConfigurationSource
+from .yaml_configuration_source import YamlConfigurationSource
 
 __all__ = [
     "ConfigurationManager",
     "ConfigurationSource",
     "EnvConfigurationSource",
+    "YamlConfigurationSource",
     "value"
 ]

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

@@ -4,11 +4,9 @@ Configuration handling module.
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-import os
 from typing import Optional, Type, TypeVar
-from dotenv import load_dotenv
 
-from aspyx.di import injectable, Environment, CallableProcessor, LifecycleCallable, Lifecycle
+from aspyx.di import injectable, Environment, LifecycleCallable, Lifecycle
 from aspyx.di.di import order, inject
 from aspyx.reflection import Decorators, DecoratorDescriptor, TypeDescriptor
 
@@ -67,7 +65,7 @@ class ConfigurationManager:
 
     def get(self, path: str, type: Type[T], default : Optional[T]=None) -> T:
         """
-        Get a configuration value by path and type, with optional coercion.
+        Retrieve a configuration value by path and type, with optional coercion.
         Arguments:
             path (str): The path to the configuration value, e.g. "database.host".
             type (Type[T]): The expected type.
@@ -119,54 +117,6 @@ class ConfigurationSource(ABC):
         return the configuration values of this source as a dictionary.
         """
 
-@injectable()
-class EnvConfigurationSource(ConfigurationSource):
-    """
-    EnvConfigurationSource loads all environment variables.
-    """
-
-    __slots__ = []
-
-    # constructor
-
-    def __init__(self):
-        super().__init__()
-
-        load_dotenv()
-
-    # implement
-
-    def load(self) -> dict:
-        def merge_dicts(a, b):
-            """Recursively merges b into a"""
-            for key, value in b.items():
-                if isinstance(value, dict) and key in a and isinstance(a[key], dict):
-                    merge_dicts(a[key], value)
-                else:
-                    a[key] = value
-            return a
-
-        def explode_key(key, value):
-            """Explodes keys with '.' or '/' into nested dictionaries"""
-            parts = key.replace('/', '.').split('.')
-            d = current = {}
-            for part in parts[:-1]:
-                current[part] = {}
-                current = current[part]
-            current[parts[-1]] = value
-            return d
-
-        exploded = {}
-
-        for key, value in os.environ.items():
-            if '.' in key or '/' in key:
-                partial = explode_key(key, value)
-                merge_dicts(exploded, partial)
-            else:
-                exploded[key] = value
-
-        return exploded
-
 # decorator
 
 def value(key: str, default=None):
@@ -188,8 +138,8 @@ def value(key: str, default=None):
 @injectable()
 @order(9)
 class ConfigurationLifecycleCallable(LifecycleCallable):
-    def __init__(self, processor: CallableProcessor,  manager: ConfigurationManager):
-        super().__init__(value, processor, Lifecycle.ON_INIT)
+    def __init__(self,  manager: ConfigurationManager):
+        super().__init__(value, Lifecycle.ON_INJECT)
 
         self.manager = manager